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Following is a description of the new function added to the OS/2 Control Program Application Program- 
ming Interface (API) by OS/2 Version 1 .2. 


Support Provided by OS/2 Version 1.2 File Systems 

OS/2 Version 1.2 supports the OS/2 File Allocation Table (FAT) and the installable High Performance File 
System (HPFS), as well as any File System Drivers (FSDs) written for OS/2 Version 1.2. Both OS/2 
Version 1.2 file systems provide the following support for the API: 

• DOS logical file and directory structure 

• DOS format (8.3 filename format) naming conventions 

• Universal naming conventions (UNO) 

• Partitioning of logical volumes 

• Redirection or connection to remote file systems 

• Extended Attributes (EAs) 

• Global file name character processing. 

In addition, the High Performance File System provides support for applications that recognize long file 
names. (See “Support Specific to FSDs.’') 

The following API function allows an application to determine the maximum path length allowed by the 
file system currently in use: 

DosQSysInfo Returns the maximum path length allowed by the file system. An application 

calls this function during initialization. 


Creating File Objects with Extended Attributes 


Support for applications that are aware of extended attributes and use them to manipulate file objects 

(files and subdirectories) is provided by the following API functions: 

DosOpen2 Creates a file, opens an existing file, or replaces an existing file. These files 

may have extended attributes associated with them. In addition to standard attri- 
butes, which are set as part of the directory entry, extended attributes (EAs) can 
be defined and associated with a newly created file. 

DosMkDir2 Creates a subdirectory. EAs can be defined and associated with the subdirec- 

tory. 

DosFlndFirst2 Finds names of file objects that have particular EAs associated with them. This 

call is used in conjunction with DosFindNext and DosFindClose. 

DosEnumAttribute Identifies EAs associated with an existing file. This call returns the lengths of EA 
names and values, as well as EA ASCIIZ names. This information is used to cal- 
culate the buffer space required to hold EA information returned by a 
DosQFilelnfo or DosQPathlnfo request. 


The following API functions allow an application to specify EA information levels for the purpose of que- 
rying and setting extended attributes: 


DosQPathlnfo 

DosSetPathlnfo 

DosQFilelnfo 

DosSetFilelnfo 


Returns attributes and EA names and values associated with a file object. Query 
may be made with either the name of a file or subdirectory, or a file handle. 

Sets attributes and EA names and values for a file or subdirectory. 

Returns attributes and EA names and values associated with an open file. (This 
function is an enhancement to an existing function.) 

Sets attributes and EA names and values for an open file. (This function is an 
enhancement to an existing function.) 


Comprehensive guidelines for defining standard EAs as well as application-defined EAs may be found in 
the “File and Disk Management” chapter of the Programming Guide. EA data types and data structures 
are also discussed. 
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Copying File Objects 

The following API function supports copying of file objects that may have extended attributes: 

DosCopy Copies file objects and their associated attributes and EAs from the source 

directory to the target directory. 

Repetitive Operations on File Objects 

The following API function provides global file-name character processing support: 

DosEdltName Searches for and edits the names of file objects. This function is used in con- 

junction with DosCopy and DosMove to perform repetitive operations on file 
objects. 

Network I/O Operations 

The following API function provides an efficient means of performing I/O to a local or remote FSD or FAT, 

whose access is being controlled by a network application. 

DosFllelO Performs combined lock and unlock, seek, and read or write operations on mul- 

tiple regions within a file. 


Support Specific to FSDs 

The High Performance File System and any other FSDs written for OS/2 Version 1.2 use an extended 
standard interface and provide support for applications that recognize long file names. OS/2 Version 1.2 
identifies these applications as belonging to the NEWFILES class of application by a bit that is set in the 
header of the executable file at link time. This bit is not inherited by any child processes started by the 
application. 

The following API functions are provided for network applications that need to control local and remote 
access to OS/2 FSDs: 

DosFSAttach Attaches or detaches a drive to or from a local or remote FSD. This function also 

attaches or detaches a pseudo-character device (such as a named pipe) to the 
FSD. 

DosQFS Attach Returns information about a local or remote FSD. This function also returns 

information about a character or pseudo-character device attached to the FSD. 

DosFSCtl Provides an extended standard interface between a network application and an 

FSD. 

The High Performance File System also supports caching of directories, data, and file system structures. 
The following API function allows an application to prevent the corruption of disk files, which can occur if 
data is still in cache when the system is powered off: 

DosShutdown Flushes data in cache to disk and prevents further caching of data. 

This call is used by the Presentation Manager. 


File System Compatibility Considerations 

The OS/2 Version 1.2 FAT continues to provide support for OS/2 applications written for Versions 1.0 and 
1.1 (as well as any applications written for 1.2) that recognize only DOS format (8.3 filename format) file 
names. By default, an application of this type is considered a OLDFILES class application. A OLDFILES 
application exhibits the same behavior as when running in OS/2 Versions 1.0 and 1.1. This behavior is on 
a per-process basis and extends to any DLL called by the process. Therefore, when a OLDFILES applica- 
tion passes a long file name with a file system request, the request is rejected. 
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Following Is a list of the file system function calls whose acceptance or rejection of long file names is 
determined by the class of application making the request: 


DosCopy 

DosDelete 

DosExecPgm 

DosFindFirst 

DosFindNext 

DosQFSAttach 

DosFSAttach 

DosGetMessage 

DosGetModHandle 

DosGetModName 

DosLoadModule 


DosMkDir 

Dos Move 

DosOpen 

DosQAppType 

DosQFileMode 

DosQPathlnfo 

DosRmDir 

DosSearchPath 

DosSetFileMode 

DosSetPath 

DosStartSession 


The following API functions, which provide EA support and are separate from their counterparts that have 
similar names and functions for compatibility reasons, also reject a request from a OLDFILES class appli- 
cation that passes a long file name: 

DosOpen2 

DosMkDir2 

DosFlndFir$t2 


The only restriction placed on a OLDFILES class of application concerning files with extended attributes 
is that If critical EAs have been defined and associated with a file, a request to open the file will be 
rejected. EAs that are defined as critical EAs contain information that is essential to the intended use of 
the file. 


Family API Considerations 

A family application, written to run in the DOS environment as well as the OS/2 environment, also 
behaves the same as when running in DOS mode for OS/2 Versions 1.0 and 1.1. When a long file name is 
passed with a file system function request, the name is truncated and is not considered an error. Setting 
the NEWFILES bit has no effect in DOS mode. 


Device Driver Support 

The following API functions have been added to support device drivers: 

DosDevlOCtl2 Performs control functions on an open device. Supports device drivers that must 

receive generic IOCTL packets with associated length fields. 

DosSMRegisterDD Registers a device driver with the session manager. The device driver is noti- 
fied whenever a session switch occurs. 


I/O Subsystems Support 

The following API function has been added to the OS/2 keyboard subsystem: 

KbdGetHWId Returns the hardware-generated identification value for the attached keyboard. 

The following API function has been added to the OS/2 video subsystem: 

VioGlobalReg Allows global registration of a video subsystem for all full-screen sessions. The 

video subsystem is notified whenever an application running in a full-screen 
session completes a video function request. 
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Preface 


About this Book 

The Operating System/2 Version 1.2 (OS/2) Control Program Programming Reference is a detailed tech- 
nical reference for application programmers creating programs using OS/2 Dos, Kbd, Mou, and Vio 
system functions. These functions are also called the control program functions. The control program 
functions carry out such tasks as allocating memory and performing file, keyboard, mouse, and video 
operations. 

Chapter 1 contains important information. You should read it before using this book. 

The reference does not give guidance on how to use the calls, nor does it contain information about how 
the calls are related to each other. It is intended to be used in conjunction with the Operating System/2 
Version 1.2 Programming Guide . 

Prerequisite Knowledge 

The Programming Tools and Information library is intended for professional application developers know- 
ledgeable in at least one programming language in which OS/2 programs can be written. The informa- 
tion in the Programming Tools and Information library assumes you are new to programming with OS/2 
and the Presentation Manager. You should understand the OS/2 services available to users. Further 
information on these can be obtained from the OS/2 Product library. 

Related Publications 

The Operating System/2 Version 1.2 Programming Overview introduces the programming concepts that 
you should understand before you begin developing applications to run on OS/2, and describes the set of 
books, toois, programming aids, and sample programs that make up the OS/2 Programming Tools and 
Information Library. 

Details of publications for OS/2 Version 1.2 and related products are shown in the Library Diagram on the 
following page. 
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OS/2 Product 


Separate Order 
(no charge) 


Systems Application 
Architecture 


IBM Operating System/2 
Standard Edition 
Version 1.2 

Getting Started 

Using Advanced Features 

Product Information 

6024926 3.5" diskette 
6024930 5.25" diskette 


OS/2 Programming Tools 
and Information 


IBM Operating System/2 
Version 1.2 

Installation 

Programming Overview 
Programming Guide 
Building Programs 
Dialog Tag Language 
Guide and Reference 
Dialog Manager Guide 
and Reference 
Dialog Manager and 
Dialog Tag Language 
Reference Summary 
Programming Reference 
(3 books) 

Bindings Reference for 
Presentation Manager 
(4 books for COBOL/2, 
FORTRAN/2, C/2, and 
Macro Assembler/2) 

I/O Subsystems and 
Device Support 
(2 books) 

Systems Application 
Architecture 
Common User Access: 
Advanced Interface 
Design Guide 

6024929 


Keyboards and Code Pages 
6280345 

Available Separately 


Command Reference 

6024928 

Service Coordinator's 
Guide 

15F2214 


Programming Languages 


IBM Basic Compiler/2 
Version 1.0 6280179 


IBM Macro Assembler/2 
Version 1.0 6280181 


IBM Pascal Compiler/2 
Version 1.0 6280183 


IBM FORTRAN/2 
Version 1.02 6280185 


IBM COBOL/2 
Version 1.0 6280207 


IBM C/2 

Version 1.1 6280284 


An Overview 


GC26-4341 


Writing Applications: 
A Design Guide 

SC26-4362 


Common User Access: 
Advanced Interface 
Design Guide 
SC26-4582 


Common User Access: 
Basic Interface Design 
Guide 
SC26-4583 


Common Programming 
Interface 


C Reference - Level 2 
SC09-1308 


COBOL Reference 
SC26-4354 


Dialog Reference 
SC26-4356 


FORTRAN Reference 
SC26-4357 


Procedures Language 
Reference 
SC26-4358 


Presentation Reference 
SC26-4359 


Notes: 

1. CodeView ™ is available with IBM C/2 Version 1.1 and upon request. An order form is available with 
the OS/2 Standard Edition Version 1 .2 Product. It is also compatible with the Macro Assembler/2, 
Pascal Compiler/2, and BASIC Compiler/2 listed above. 


™ Trademark of Microsoft Corporation 
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2. IBM 012 Version 1.1 is available on 5.25 in. diskette. An order form is available in the Cf 2 package. 

3. See your IBM representative for ordering information. 
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Organization off this Book 

Chapter 1, “Introduction” on page 1-1 

This chapter contains important information about the following: 

• Notation conventions 

• Conventions used in Function Descriptions 

• Format of Call Descriptions 

You should read it before using this book. 

Chapter 2, “Control Program Function Calls” on page 2-1 

Chapter 3, “Keyboard Function Calls” on page 3-1 

Chapter 4, "Mouse Function Calls” on page 4-1 

Chapter 5, "Video Function Calls” on page 5-1 

Appendix A, "Errors Returned from Base OS/2 Calls” on page A-1 

Index 
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Chapter 1. Introduction 

This chapter contains important information. You should read it before using this book. 

The purpose of this reference is to provide information about control program (base system) function 
calls, messages, constants, and so on. The control program function calls include four function groups. 
These function groups provide the basic operating-system features of OS/2. The four function groups are: 

Dos The Dos function calls can be used in full-screen and Presentation Manager sessions to 

perform basic operating-system operations, such as file input/output, memory allocation, and 
thread and process creation/control/communication. 

Kbd The Kbd function calls can be used in full-screen sessions to perform keyboard operations. 

Mou The Mou function calls can be used in full-screen sessions to perform mouse operations. 

Vlo The Vio function calls can be used in full-screen sessions to perform video operations. 

The bindings for both IBM CI2 and IBM Macro Assembler/2 languages are given at the end of each func- 
tion call. An example In C/2 language is also shown at the end of some function calls. 


Conventions Used in Function Descriptions 

The documentation of each function contains these sections: 

Function name The function name is listed in alphabetic order at the top of each page followed by a 
brief description of the function. 

Icon An icon is at the top of each page opposite the function name, where applicable. The 

icon is used to identify certain characteristics or exceptions. The absence of an icon 
indicates there are no restrictions. 

FAPI This indicates that the function is a family API function. A family API 

function can be used in programs for either OS/2 or DOS. 

xPM This indicates that the function is not applicable to Presentation 

Manager (some Dos, all Kbd, and all Mou calls). 

xWPM This indicates that the function is not applicable to windowable or Pres- 
entation Manager calls (some VIO calls). 

Parameters Each parameter is listed with its C/2 language data type, parameter type, and a brief 

description. 

• All data types are written in uppercase. A data type 'Pxxxxxxx' implicitly 
defines a pointer to the data type 'xxxxxxx'. The C/2 language data types, struc- 
tures, and constants are defined in the OS2DEF.H and BSE*.H include files. The 
include files are in the TOOLKT12\C\INCLUDE directory. 

The term NULL applied to a parameter indicates the presence of the parameter, 
but with no value. 

• There are three parameter types: 

Input Specified by the programmer. 

Output Returned by OS/2. 

Input/Output Specified by the programmer and modified by OS/2. 

• A brief description is provided with each parameter. Where appropriate, 
restrictions are also included. In some cases, the parameter points to a struc- 
ture that is also defined in the parameter description. 

rc A list of possible return codes or errors (where appropriate) is included in this 

section. Some functions do not have return codes or error messages. Refer to 
Appendix A for a complete list of ail return codes and their descriptions. The return 
codes are listed in Appendix A in alphabetic order and in numeric order. 
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Remarks The remarks section contains additional information about the function, where 

required. 

Named Pipe Considerations 

This section contains additional information about the function when using Named 
Pipes, where required. 

Family API Considerations 

This section contains additional information about the function when the application 
is intended for DOS, where required. 

PM Considerations This section contains additional information about the function when using Presenta- 
tion Manager, where required. 

Bindings C/2 and Macro Assembler/2 language bindings are provided with each function. The 

bindings are derived from the include files. The minimum include statement (#define 
INCL_xxxx for C/2 and INCL_xxxx EQU ? for Macro Assembler/2) is provided in each 
binding. 

Example An example is shown in C/2 language for some functions. 

Programming Note: The functions in this book are named in mixed-case for readability, but are known to 
the system as uppercase character strings. If you are using a compiler that generates a mixed- 
case external name, you should code the OS/2 function calls in uppercase. 
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Chapter 2. Control Program Function Calls 


This chapter reflects the Dos API interface of OS/2 only. The Dos function calls can be used in full-screen 
and Presentation Manager sessions to perform basic operating-system operations, such as file 
input/output, memory allocation, and thread and process creation/control/communication. 

Notes: 

1. Calls marked xPM are not supported by Presentation Manager, and must not be used by Presenta- 
tion Manager applications. An error code is returned if any of these calls are issued. 

2. Calls marked xWPM are not windowable and are not supported by Presentation Manager. They can 
be used in OS/2 mode. 

3. Calls marked FAPI are present in the Family API. 

4. Those calls without an icon are: 

• Windowable 

• Presentation Manager 

• Full-screen 

• Not Family API. 
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DosAllocHuge - 
Allocate Huge Memory 


FAPI 


This call allocates multiple segments as a huge block of memory. 


DosAllocHuge (NumSeg, Size, Selector, MaxNumSeg, AllocFlags) 


Parameters 

NumSeg (USHORT) - input 

Number of 65536-byte segments to be allocated. 

Size ( USHORT) - input 

Number of bytes to be allocated in the last (non-65536-byte) segment. A value of zero indicates 
none. 

Selector (PSEL) - output 

Address where the selector of the first segment allocated is returned. 

MaxNumSeg ( USHORT) - input 

Maximum number of 65536-byte segments this object occupies as a result of any subsequent 
DosReallocHuge (see “DosReallocHuge - Change Huge Memory Size” on page 2-287). If 
MaxNumSeg is 0, OS/2 assumes this segment will never be increased by DosReallocHuge beyond its 
original size, though it may be decreased. This value is ignored in the DOS mode. 

AllocFlags ( USHORT) - input 

Bit indicators describing the characteristics of the segment allocated. The bits that can be set and 
their meanings are: 

Bit Description 

15-4 Reserved and must be set to zero. 

3 If segment is shared, it can be decreased in size by DosReallocHuge. 

2 Segment may be discarded by the system in low memory situations. 

1 Segment is shareable through DosGetSeg. 

0 Segment is shareable through DosGiveSeg. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR_INVALID_PARAMETER 

212 ERRORJ.OCKED 

Remarks 

DosAllocHuge allows a process to allocate a large amount of memory by telling the system how many 
64KB segments it needs and whether it requires an additional partial segment. The system allocates the 
memory, which is movable and swappable, and returns a selector to the first segment. When this 
selector is used with a call, the requested function is performed for the entire block of memory. 

Each segment of a huge memory allocation has a unique selector. To determine the remaining selectors 
of a huge memory allocation, issue DosGetHugeShift, which returns a shift count. To compute the next 
sequential selector, take the value 1 and shift it left by the number of bits specified in shift count. Use the 
resulting value as an increment to add to the previous selector, using the selector returned by 
DosAllocHuge as the first selector. For example: 

• Assume DosAllocHuge is issued with NumSeg equal to 3, and that the number 63 is returned for the 
selector of the first segment. 

• If DosGetHugeShift returns a shift count of 4, shifting the value "1 11 by this amount results in an incre- 
ment of 16. 

• Adding this increment to selector number 63 produces 79 for the second selector. Adding the same 
increment to selector number 79 yields 95 for the third selector. 
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FAPI 


DosAllocHuge - 
Allocate Huge Memory 


Like single segment memory allocated with DosAilocSeg, huge memory can be designated as shareable 
by other processes and discardable by the system when no longer needed. Allocating a huge block of 
memory as discardable automatically locks the memory for use by the caller. When one segment of a 
huge allocation is discarded by the system, this forces the discard of all the other segments. See 
DosAilocSeg for more information relating to discardable and shared segments. 

Applications should be discretionary in claiming large memory when doing so can impair system per- 
formance. To test system memory availability, issue DosMemAvail. This call returns the size of the 
largest block of unallocated memory. Although this value can change at any time because of system 
activity, it can provide a good indication of the system memory state. 

Memory allocated by DosAllocHuge is freed by DosFreeSeg. One call to DosFreeSeg, passing the 
selector returned from a DosAllocHuge, frees ail of the memory allocated. 

Note: This request may be issued from privilege level 2. However, the segment is allocated as a privi- 
lege level 3 segment. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following con- 
siderations apply to DosAllocHuge when coding for the DOS mode: 

• Requested size value is rounded up to the next paragraph (16-byte) 

• Selector is the actual segment address allocated. 


C Language 

#define INCL.DOSMEMHGR 

USKORT rc = DosAllocHuge(Num$eg, Size, Selector, MaxNumSeg, AllocFlags); 


USKORT 


NumSeg; 

/* 

Number of 65536- byte segments */ 

USKORT 


Size; 

/* 

Number of bytes in last segment */ 

PSEL 


Selector; 

/* 

The first Selector allocated (returned) */ 

USKORT 


MaxNumSeg; 

/* 

Max number of 65536-byte segments */ 

USKORT 


AllocFlags; 

/* 

Allocation flags */ 

USHORT 


rc; 

/* 

return code */ 

Assembler Language 


EXTRN 

DosAllocHuge: FAR 



INCLJ30SMEMMGR 

EQU 1 



PUSH 

WORD 

NumSeg 

; Number of 65536-byte segments 

PUSH 

WORD 

Size 

; Number of bytes in last segment 

PUSH© 

WORD 

Selector 

;The first Selector allocated (returned) 

PUSH 

WORD 

MaxNumSeg 

;Max number of 65536-byte segments 

PUSH 

WORD 

AllocFlags 

; Allocation flags 

CALL 

DosAllocHuge 




Returns WORD 
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DosAllocHuge - 
Allocate Huge Memory 


FAPI 


Example 

This example requests a block of memory with 4 segments, the last segment having 1,040 bytes. The 
block of memory will never be larger than 8 segments. The memory can be shared with DosGiveSeg API 
calls. The system can discard the memory if it needs too. 

Idefine INCL_DOSMEMMGR 

Idefine NUMBER OF SEGMENTS 4 

Idefine BYTESJN_LAST_SEGMENT 1040 

Idefine MAXIMUM SEG SIZE 8 

Idefine ALL0C_FLAG SEGJIVEABLE | SEG_D1SCARDABLE 

SEL Selector; 

USHORT rc; 


rc = DosAllocHuge (NUMBER OF SEGMENTS, 

BYTES JN_LAST_SEGMENT , 
&Selector, 

MAXIMUM.SEG SIZE. 
ALLOC_FLAG) ; 


/* # of 65536-byte segments */ 
/ie # of bytes in last segment */ 
/* The 1st selector allocated */ 
/ie Max number of segments ie/ 
fie Allocation flags iej 
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FAPI 


DosAllocSeg - 
Allocate Segment 


This call allocates a segment of memory to a requesting process. 


DosAllocSeg (Size, Selector, AllocFlags) 


Parameters 

Size ( USHORT) - input 

Number of bytes requested. The value specified must be less than or equal to 65535, A value of zero 
indicates 65536 bytes. 

Selector (PSEL) - output 

Address where the selector of the segment allocated is returned. 

AllocFlags ( USHORT) - input 

Bit indicators describing the characteristics of the segment being allocated. The bits that can be set 
and their meanings are: 

Bit Description 

15 — 4 Reserved and must be set to zero. 

3 If segment is shared, it can be decreased in size by DosReallocSeg. 

2 Segment may be discarded by the system in low memory situations. 

1 Segment is shareable through DosGetSeg. 

0 Segment is shareable through DosGiveSeg. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

8 ERROR_NOT_ENOUGH_MEMORY 

87 ERROR JNVALID_PAR AM ETER 

Remarks 

DosAllocSeg allows a process to allocate a data segment up to 64KB in size, which is movable and 
swappable by the system. If your application needs to accommodate a large data structure that exceeds 
the 64KB limit, DosAllocHuge may be issued to allocate multiple segments as one huge block of memory. 

A segment allocated by DosAllocSeg with AllocFlags bit 2 set can be discarded by the system to remedy 
a low memory situation when the segment is not in use. Upon allocation, a discardable segment is 
locked and ready for access. The caller issues DosUnlockSeg when it is finished using the segment. The 
next time the caller needs to access the segment, it must issue DosLockSeg. During the time a segment 
is locked, it cannot be discarded, but it can still be swapped. 

Allocate memory as discardable when it is needed to hold data for only short periods of time; for 
example, saved bit map images for obscured windows. Once the system discards a segment, the caller 
must reallocate the segment with DosReallocSeg and regenerate the data. Reallocating the segment 
automatically locks it for the first access. 

A segment may also be designated as shared with another process. If a process issues DosAllocSeg 
with AllocFlags bits 0 and 1 set, the process can then issue DosGiveSeg to obtain a selector for the 
sharer to use. The process then passes the selector to the sharer using some means of interprocess 
communication. For the sharer to access the shared segment, it must issue DosGetSeg with the passed 
selector. If the shared segment has been designated discardable (AllocFlags bit 2 is also set), the sharer 
must also issue DosLockSeg to lock the segment. 

Memory allocated with DosAllocSeg is freed by a call to DosFreeSeg. 

Note: This request may be issued from privilege level 2. However, the segment is allocated as a privi- 
lege level 3 segment. 
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DosAllocSeg - 
Allocate Segment 


FAPI 


Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to DosAllocSeg when coding for the DOS mode: 

• Requested Size value is rounded up to the next paragraph (16-byte). 

• Selector is the actual segment address allocated. 

• AllocFlags must be set to zero. 


C Language 

^define INCLJOSMEMMGR 

USHGRT rc = DosAl locSeg(Si ze, Selector, AllocFlags); 


USHORT 

Size; 

/* Number of bytes requested */ 

PSEL 

Selector; 

/* Selector allocated (returned) */ 

USHORT 

AllocFlags; 

/* Allocation flags */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosAllocSeg: FAR 
INCL_DOSMEMMGR EQU 1 

PUSH WORD Size ; Number of bytes requested 

PUSH? WORD Selector Selector allocated (returned) 

PUSH WORD AllocFlags ;A1 location flags 

CALL DosAl 1 ocSeg 

Returns WORD 

Example 

This example requests a segment of memory with 30,128 bytes. The segment can be shared with a 
DosGetSeg API call. 

^define INCL.DOSMEMMGR 

#define NUMBER_OF_BYTES 30128 
#define ALLOC JLAG SEGJ2ETTABLE 

SEL Selector; 

USHORT rc; 

rc s DosAl 1 ocSeg (NUMBER_OF_BYTES, /* # of bytes requested */ 

&Selector, /* Selector allocated */ 

ALL0C_FLAG) ; /* Allocation flags */ 

The following example requests a segment of memory with 4,000 bytes. The following example also 
shows how to suspend and resume execution of a thread within a process. The main thread creates 
Thread2 and allows it to begin executing. Thread2 iterates through a loop that prints a line and then 
sleeps, relinquishing its time slice to the main thread. After one iteration by Thread2, the main thread 
suspends Thread2 and then resumes it. Subsequently, Thread2 completes the remaining three iterations. 
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FAPI 


DosAllocSeg - 
Allocate Segment 


Idefine INCL_D0SPR0CE$S 
linclude <os2.h> 

Idefine SEGSIZE 4000 /* Number of bytes requested in segment */ 

#de fine ALLOCFLAGS 0 /* Segment allocation flags - no sharing */ 

Idefine SLEEPSHORT 5L /* Sleep interval - 5 milliseconds */ 

Idefine SLEEPLONG 75L /* Sleep interval - 75 milliseconds */ 

Idefine RETURNJXDE 0 /* Return code for DosExit() */ 

VOID API ENTRY Thread2() 

{ 

USHORT i ; 

/* Loop with four iterations */ 
for (i =*1 ; i<5; i++) 

{ 

printf("In Thread2, i is now %d\n‘\ i); 

/* Sleep to relinquish time slice to main thread */ 

DosSl eep (SLEEPSHORT) ; /* Sleep interval */ 

} 

DosExit(EXIT_THREAD, /* Action code - end a thread */ 

RETURN_C0DE) ; /* Return code */ 

} 


main() 

{ 

TID ThreadID; 

SEL ThreadStackSel ; 

PBYTE StackEnd; 

USHORT rc; 

/** Allocate segment for thread stack; make pointer to end of stack. **/ 
/** We must allocate a segment in order to preserve segment protection **/ 
/** for the thread. **/ 

rc a DosAllocSeg(SEGSIZE, /* Number of bytes requested */ 

&ThreadStackSel , /* Segment selector (returned) */ 

ALLOCFLAGS); fit Allocation flags - no sharing */ 

StackEnd - MAKEP (ThreadStackSel , SEGSIZE-1); 

/** Start Thread2 **/ 

i f ( ! (rc=DosCreateThread( (PFNTHREAD) Thread2, /* Thread address */ 

&ThreadID, /* Thread ID (returned) */ 

StackEnd))) /* End of thread stack */ 
printf ( w Thread2 created. \n 11 ); 

fie Sleep to relinquish time slice to Thread2 */ 
if (l (DosSl eep (SLEEPSHORT))) /* Sleep interval ie/ 

printf ("Slept a little to let Thread2 execute.\n“); 

/ieieieieie Suspend Thread2, do seme work, then resume Thread2 ieieieieie/ 
if(!(rc a DosSuspendThread(ThreadID))) /ie Thread ID */ 

pri nt f ( "Thread2 SUSPENDED. \n") ; 

printf ("Perform work that will not be interrupted by Thread2.\n“); 
if (!(rc=DosResumeThread (ThreadID))) fie Thread ID ie/ 

printf ("Thread2 RESUMED. \n n ); 
printf ("Now we may be interrupted by Thread2.\n") ; 

/ie Sleep to allow Thread2 to complete */ 

DosSl eep (SLEEPLONG); /* Sleep interval ie/ 

} 


/ie Thread identification ie/ 

/ie Segment selector for thread stack ie/ 
/ie Ptr. to end of thread stack ie/ 
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DosAllocShrSeg - 

Allocate Named Shared Segment 


This call allocates a named shared memory segment to a process. 


DosAllocShrSeg (Size, Name, Selector) 


Parameters 

Size ( USHORT) - input 

Number of bytes requested. The value specified must be less than or equal to 65535. A value of 0 
indicates 65536 bytes. 

Name ( PSZ ) - input 

Address of the name string associated with the shared memory segment to be allocated. Name 
specifies the symbolic name for the shared memory segment. The name string is an ASCIIZ string in 
the format of an OS/2 file name in a subdirectory called \SHAREMEM\. The name string must include 
the prefix \SHAREMEM\. For example \SHAREMEM\name. 

Selector (PSEL) - output 

Address where the selector of the allocated segment is returned. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOT_ENOUGH_M EMORY 

123 ERRORJNVALID_NAMi 

183 ERROR_ALREADY_EXISTS 

Remarks 

DosAllocShrSeg allocates a named segment of up to 64KB in size, which is movable and swappable. The 
segment can be shared by any process that knows the name of the segment. 

To access the shared segment, another process issues DosGetShrSeg, specifying the segment name. 

The selector returned by DosGetShrSeg is the same as the one returned by DosAllocShrSeg. 

The maximum number of segments a process can define with DosAllocShrSeg or access with 
DosGetShrSeg is 256. 

Note: This request may be issued from privilege level 2. However, the segment is allocated as a privi- 
lege level 3 segment. 

C Language 

#def1ne INCLJ30SMEMMGR 


USHORT rc = DosAllocShrSeg (Size, Name, Selector); 


USHORT 

Size; 

/* Number of bytes requested */ 

PSZ 

Name; 

/* Name string */ 

PSEL 

Selector; 

/* Selector allocated (returned) 

USHORT 

rc; 

fie return code */ 


2-8 


Control Program Programming Reference 




DosAllocShrSeg - 
Allocate Named Shared Segment 

Assembler Language 

EXTRN DosAllocShrSeg: FAR 
INCL.DOSMEMMGR EQU 1 

PUSH WORD Size ; Number of bytes requested 

PUSH® ASCI IZ Name ;Name string 

PUSH® WORD Selector jSelector allocated (returned) 

CALL DosAllocShrSeg 

Returns WORD 


Example 

This example requests a segment of memory with 27 bytes named "stock.dat". 

Idefine INCLJ30SMEMMGR 

Idefine NUMBER OF BYTES 27 

Idefine NAME_SEG "\\SHAREMEMWstock.dat " 

SEL Selector; 

USHORT rc; 

rc = DosAllocShrSeg (NUMBER OF BYTES, /* I of bytes requested */ 

NAME_$EG,~ /* Name string */ 

&Selector); /* Selector allocated */ 
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DosBeep — fapi 

Generate Sound From Speaker 


This call generates sound from the speaker. 


DosBeep (Frequency, Duration) 


Parameters 

Frequency ( USHORT) - input 

Tone in Hertz (cycles per second) in the range 37 through 32767. 

Duration ( USHORT) - input 

Length of the sound in milliseconds. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

395 ERROR_INVALID_FREQUENCY 

Remarks 

DosBeep executes synchronously. An application program that invokes DosBeep waits until the specified 
number of milliseconds expire before it resumes execution. 

C Language 

♦def i ne INCl_DOSPROCESS 

USHORT rc » DosBeep (Frequency, Duration); 

USHORT Frequency; /* Hertz (Hz) */ 

USHORT Duration; /* Length of sound */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosBeep: FAR 
INCl_DOSPROCESS EQU 1 

PUSH WORD Frequency frequency (in Hertz) 

PUSH WORD Duration ; Length of sound (in milliseconds) 

CALL DosBeep 

Returns WORD 

Example 

This example generates a beep for 1 second (1,000 milliseconds) at a frequency of 1,380. 

♦define INCL_DOSPROCESS 

♦define BEEP_FREQUENCY 1380 
♦define BEEP_DllRATI0N 1000 

USHORT rc; 

rc = DosBeep(BEEP_FREQUENCY, 

BEEPJJURATION) ; 
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fapi DosBufReset - 

Commit File’s Cache Buffers 


This call flushes a requesting process's cache buffers for a specific file handle or for ail file handles 
attached to that process. This call is also used with the handle of a named pipe to synchronize a dialog 
between communicating processes. 


DosBufReset (FileHandle) 


Parameters 

FileHandle (HFILE) - input 

File handle whose buffers are to be flushed. If FileHandle = OxFFFFH, all of the process’s file 
handles are flushed. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

2 ERROR_FILE_NOT_FOUND 

5 ERROR_ACCESS_DENIED 

6 ERROR_INVALlD_HANDLE 

Remarks 

Upon issuing DosBufReset for a file handle, the file’s buffers are flushed to disk and its directory entry 
updated as if the file had been closed; however the file remains in an open state. 

Usage of this call to write out all files belonging to the requesting process should be administered with 
caution. When the files reside on removable media (diskettes), a call to DosBufReset could have the 
undesirable effect of requiring the user to insert and remove a large number of diskettes. 

Named Pipe Considerations 

Issuing DosBufReset for a named pipe performs an operation that is analogous to forcing the buffer cache 
to disk. The request blocks the calling process at one end of the pipe until all data it has written has been 
read at the other end of the pipe. 


C Language 

#define INCLJJ0SF1LEMGR 

USHORT rc B DosBufReset (Fi 1 eHandl e) ; 


HFILE 

FileHandle; 

/* File handle */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosBufReset: FAR 
INCL.DOSFILEMGR EQU 1 

PUSH WORD FileHandle ;File handle 
CALL DosBufReset 

Returns WORD 
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DosBufReset - 
Commit File’s Cache Buffers 


Example 

This example opens a file, writes some data to the file's buffer, then flushes the file's system buffer. 

Idefine INCL_DOSFILEMGR 

Idefine OPEN FILE 0x01 
Idefine CREATE FILE 0x10 
Idefine F I LE_ARCH I V E 0x20 
Idefine FILE_EXISTS 0PEN_FILE 
Idefine FILE NOEXISTS CREATE FILE 
Idefine DASD_FLAG 0 
Idefine INHERIT 0x80 
Idefine WRITE_THRU 0 
Idefine FAIL FLAG 0 
Idefine SHARE_FLAG 0x10 
Idefine ACCESS_FLAG 0x02 

Idefine FILE_NAME "test.dat" 

Idefine FILE SIZE 800L 

Idefine FILElATTRIBUTE FILE_ARCHIVE 

Idefine RESERVED 0L 

HFILE FileHandle; 

USHORT Wrote; 

USHORT Action; 

PSZ FileData[100]; 

USHORT re; 


Action a 2; 

strcpy(FileData, “Data.,."); 
i f ( i DosOpen ( F I LE_NAME , /* 

&FileHand1e, /* 

&Action, /* 

FILE_SIZE, /* 

FILE ATTRIBUTE, /* 

FILE_EXISTS | FILE_NOEXISTS, 
DASD_FLAG | INHERIT | 

WRITE THRU ! FAIL_FLAG | 
SHARE_FLAG j ACCESS_FLAG , 
RESERVED)) /* 

if(!DosWrite(FileHandle, /* 

(PVOID) FileData, /* 

sizeof(FileData), /* 

&Wrote)) /* 

rc = DosBufReset (FileHandle) ; /* 


File path name */ 

File handle */ 

Action taken */ 

File primary allocation */ 

File attribute *7 

/* Open function type */ 
/* Open mode of the file */ 


Reserved (must be zero) */ 
File handle */ 

User buffer */ 

Buffer length */ 

Bytes written */ 

File handle */ 


FAPI 
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DosCallback - 

Privilege Level 2 Call to Privilege Level 3 Routine 


This call provides a privilege level 2 IOPL segment to call a privilege level 3 application segment. 


DosCallback (Ring3Rout!ne) 


Parameters 

Ring3Rout(ne (PFN) - input 

Address of the privilege level 3 application routine to be called. 

Remarks 

This function allows a routine executing with I/O privilege (at privilege level 2) to call a segment that is 
executing at privilege level 3 and also to have the target routine execute at privilege level 3; for example, 
not to allow/require the target routine to be privilege level 2 conforming. 

The requested routine is given control at privilege level 3 and when it completes execution and returns, 
return is made to the privilege level 2 calling routine. 

Ail registers except FLAGs are passed intact across this call return sequence and may be used to pass 
parameters or data. Any addresses passed from privilege level 2 to privilege level 3 must be based on 
privilege level 3 selectors only as the privilege level 3 code does not have proper addressability to any 
privilege level 2 data selectors. 

The privilege level 2 stack can not be used to pass data to the privilege level 3 routine. 

If DosCallback is used in a nested fashion such that a privilege level 3 routine issues a call to a privilege 
level 2 routine while performing a “Callback” operation (after being invoked by “Callback” but before 
having issued a Far RET back to the privilege level 2 code), any subsequent DosCallback requests must 
complete execution and issue their corresponding Far RETs in last-in-first-out (LIFO) order. 

C Language 

Ideflne INCL_DOSDEVICES 

VOID DosCa11back(Ring3Routine) ; 

PFN Ring3Routine; /* Address of privilege level 3 routine */ 

Assembler Language 

EXTRN DosCallback: FAR 
INCL_00S0EVI CES EQU 1 

PUSH® OTHER Ring3Routine ; Address of privilege level 3 routine 
CALL DosCallback 

Returns NONE 
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DosCalINmPipe - 

Perform Procedure Call Transaction 


This call performs a “procedure call” transaction using a message pipe. 


DosCalINmPipe (FiieName, InBuffer, InBufferLen, OutBuffer, OutBufferLen, 
BytesOut, TimeOut) 


Parameters 

FiieName (PSZ) - input 

Address of the ASCIIZ name of the pipe to be opened. Pipes are named \PIPE\FileName. 

InBuffer (PBYTE) - input 

Address of the buffer to write to the pipe. 

InBufferLen ( USHORT) - input 
Number of bytes to be written. 

OutBuffer (PBYTE) - input/output 

Address of the buffer for returned data. 

OutBufferLen (USHORT) - input 

Maximum size (number of bytes) of returned data. 

BytesOut (PUSHORT) - output 

Address of the variable where the system returns the number of bytes actually read (returned). 

TimeOut (ULONG) - input 

Maximum time to wait for pipe availability. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR J=ILE_NOT_FOUND 

11 ERROR_BAD_FORMAT 

230 ERROR_BAD_PIPE 

231 ERROR J’lPE^BUSY 

233 ERROR_PIPE_NOT_CONNECTED 

234 ERROR_MORE_DATA 

Remarks 

This call is intended for use only on duplex message pipes. If this call is issued for a pipe that is not a 
duplex message pipe, ERROR_BAD_FORMAT is returned. 

This call has the combined effect on a named pipe of DosOpen, DosTransactNmPipe, and DosClose. It 
provides an efficient means of implementing local and remote procedure-call (RPC) interfaces between 
processes. 
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DosCalINmPipe - 
Perform Procedure Call Transaction 


C Language 

f define INCL.DOSNMPIPES 

USHORT rc a DosCallNmPipe(FileName, InBuffer, InBufferLen, OutBuffer, 

OutBufferLen, BytesOut, TimeOut); 


PSZ 

FileName; 

/* Pipe name */ 

PBYTE 

InBuffer; 

/* Write buffer address */ 

USHORT 

InBufferLen; 

/* Write buffer length */ 

PBYTE 

OutBuffer; 

/* Read buffer address */ 

USHORT 

OutBufferLen; 

/* Read buffer length * 

PUSHORT 

BytesOut; 

fie Bytes read (returned) */ 

ULONG 

TimeOut; 

(ie Maximum wait time */ 

USHORT 

rc; 

lie return code iel 


Assembler Language 

EXTRN DosCalINmPipe: FAR 
1NCL_D0SNMPIPES EQU 1 


PUSHO 

ASCI IZ 

FileName 

; Pi pe name 

PUSH? 

OTHER 

InBuffer 

;Write buffer 

PUSH 

WORD 

InBufferLen 

;Write buffer length 

PUSH@ 

OTHER 

OutBuffer 

;Read buffer 

PUSH 

WORD 

OutBufferLen 

;Read buffer length 

PUSHO 

WORD 

BytesOut 

; Bytes read (returned) 

PUSH 

DWORD 

TimeOut 

; Maxi mum wait time 

CALL 

DosCalINmPipe 


Returns WORD 
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DosCaseMap - 
Perform Case Mapping 


FAPI 


This call performs case mapping on a string of binary values that represent ASCII characters. 


DosCaseMap (Length, Country, Binarystring) 


Parameters 

Length ( USHORT) - input 

Length of the string of binary values to be case mapped. 

Country ( PCOUNTRYCODE ) - input/output 

Address of the country information structure: 

country (USHORT) 

Country code identifier is a binary value of the selected country code. 0 is the default country 
code. 

codepage (USHORT) 

Code page identifier is a binary value of the selected code page. 0 is the code page of the 
current process. 

Binarystring (PCHAR) - input/output 

Address of a string of binary characters to be case mapped. They are case mapped in place so the 
results appear in Binarystring and the input is destroyed. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

396 ERROR_NLSJMO_COUNTRY_FILE 

397 ERROR_NLS_OPEN_FAILED 

398 ERROR_NO_COUNTRY_OR_CODEPAGE 

399 ERROR_NLS_TABLE_TRUNCATED 

Remarks 

DosCaseMap is mainly used to map a lower case character string to an upper case character string. 
Unless the user replaces the country information file, DosCaseMap only does the conversion from lower 
case to upper case. 

The case map information is taken from the country information file. See the COUNTRY statement in the 
IBM Operating System/2 Version 12 Command Reference for information on how to specify the country 
information file. 

If countrycode is 0, the case mapping is performed using the information for the country specified in the 
COUNTRY statement in CONFIG.SYS. 

If countrycode is not 0, the case mapping is performed using the information for that country. 

If the code page identifier is 0, the case mapping is performed using the information for the current 
process code page. Refer to "DosSetCp - Set Code Page” on page 2-320 and the CHCP command in 
the IBM Operating System/2 Version 12 Command Reference for information on setting the process code 
page. If codepage is not 0, the case mapping is performed using the information for that code page. 

The returned country dependent information may be for the default country and current process code 
page or for a specific country and code page. 
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FAPI 


DosCaseMap - 
Perform Case Mapping 


C Language 

typedef struct _C0UNTRYC0DE { /* ctryc */ 

USHORT country; /* country code */ 

USHORT codepage; lie code page */ 

} COUNTRYCODE; 

Idefine INCL_DOSNLS 

USHORT rc - DosCaseMap (Length, Structure, Binarystring); 

USHORT Length; lie Length of string to case map ie/ 

PCOUNTRYCODE Structure; lie Input data structure iel 

PCHAR Binarystring; fie Address of binary string */ 

USHORT rc; lie return code */ 

Assembler Language 

COUNTRYCODE struc 

ctryc_country dw ? ; country code 
ctrycjrodepage dw ? ;code page 

COUNTRYCODE ends 

EXTRN DosCaseMap: FAR 
INCL_DOSNLS EQU 1 

PUSH WORD Length ; Length of string to case map 

PUSH® OTHER Structure ; Input data structure 

PUSH® OTHER Binarystring ; Binary string 

CALL DosCaseMap 

Returns WORD 

Example 

This example case maps a string for the default country and code page 850. 

#define INCLJJOSNLS 

#define CURRENT_COUNTRY 0 
#define NLS_CODEPAGE 850 

COUNTRYCODE Country; 

CHAR BinString [30] ; 

USHORT rc; 


Country. country = CURRENTJXJUNTRY; 
Country. codepage a NLS_CODEPAGE; 
strepy (Bi nStri ng, " Howdy") ; 
rc = DosCaseMap (si zeof (BinString) , 
&Country, 
BinString); 


lie Country code iel 
lie Code page */ 
lie String to map ie/ 
lie Length of string iel 
lie Input data structure iel 
lie String ie/ 
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DosChDir - 

Change Current Directory 


FAPI 


This call defines the current directory for the requesting process. 


DosChDir (DirName, Reserved) 


Parameters 

DirName ( PSZ ) - input 

Address of the ASCIIZ directory path name. 

Reserved (ULONG) - input 

Reserved and must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FlLE_NOT_FOUND 

3 ERROR_PATH_NOT_FOUND 

5 ERROR_ACCESS_DENIED 

8 ERROR_NOT_ENOUGH_M EMORY 

26 ERROR_NOT_DOS_DISK 

87 ERRORJNVALIDJ>ARAMETER 

108 ERROR_DRIVE_LOCKED 

206 ERROR_FILENAME_EXCED_RANGE 

Remarks 

The directory path is not changed if any member of the path does not exist. The current directory 
changes only for the requesting process. 

For FSDs, the case of the current directory is set according to the DirName passed in, not according to 
the case of the directories on disk. For example, if the directory “c:\bin” is created and DosChDir is 
called with DirName “c:\bin", the current directory returned by DosQCurDir will be “c:\bin M . 

Programs running without the NEWFILES bit set are allowed to DosChDir to a non-8.3 filename format 
directory. 

DosQSysInfo must be used by an application to determine the maximum path length supported by OS/2. 
The returned value should be used to dynamically allocate buffers that are to be used to store paths. 


C Language 

Idefine INCLJ30SF1LEMGR 

USHORT rc 3 DosChDir (DirName, Reserved); 


PSZ 

DirName; 

/* Directory path name * 

ULONG 

0; 

/* Reserved (must be zero) */ 

USHORT 

rc; 

/* return code */ 
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fapi DosChDir - 

Change Current Directory 


Assembler Language 

EXTRN DosChDir: FAR 
I NCL_D0SF I LEMGR EQU 1 

PUSH® ASCI IZ DirName ; Directory path name string 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosChDir 

Returns WORD 


Example 

This example changes directories to \os2\system. 

Idefine INCL_DOSFILEMGR 

Idefine PATH "\\os2\\systenT 
Idefine RESERVED OL 

USHORT rc; 

rc - DosChDir (PATH, RESERVED); 
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DosChgFilePtr - 

Move File Read/Write Pointer 


FAPI 


This call moves the read/write pointer in accordance with the type of move specified. 


DosChgFilePtr (FileHandle, Distance, MoveType, NewPointer) 


Parameters 

FileHandle ( HFILE ) - input 

Handle returned by a previous DosOpen call. 

Distance (LONG) - input 

The offset to move, in bytes. 

MoveType (USHORT) - input 

Method of moving. Specifies a location in the file from where Distance to move the read/write 
pointer starts. Values and their meanings are: 

Value Definition 

0 Beginning of the file. 

1 Current location of the read/write pointer. 

2 End of the file. Use this method to determine a file’s size. 

NewPointer (PULONG) - output 

Address of the new pointer location. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERRORJNVALID_FUNCTION 

6 ERRORJNVALIDJHANDLE 

Remarks 

The read/write pointer in a file is a signed 32-bit number. A negative value moves the pointer backward 
in the file. A positive value moves the pointer forward. DosChgFilePtr cannot be used to seek to a nega- 
tive position in the file. 

This call may not be used for a character device or pipe. 

C Language 

Idefine INCL_D0SF1LEMGR 

USHORT rc = DosChgFilePtr(FileHandle, Distance, MoveType, NewPointer); 


HFILE 

FileHandle; 

/* File handle */ 

LONG 

Distance; 

/* Distance to move in bytes */ 

USHORT 

MoveType; 

/* Method of moving (0, 1, 2) */ 

PULONG 

NewPoi nter; 

/* New Pointer Location */ 

USHORT 

rc; 

/* return code */ 
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fapi DosChgFilePtr - 

Move File Read/Write Pointer 


Assembler Language 

EXTRN DosChgFi1ePtr:FAR 
INCL_DOSFILEMGR EQU 1 


PUSH 

WORD 

FileHandle 

PUSH 

DWORD 

Distance 

PUSH 

WORD 

MoveType 

PUSHO 

DWORD 

NewPoi nter 

CALL 

DosChgFilePtr 


;Fi1e handle 

;Di stance to move in bytes 
; Method of moving (0, 1, 2) 

;New Pointer Location (returned) 


Returns WORD 


Example 

This example opens file test.dat, writes some data, and resets the file pointer to the beginning of the file. 

Idefine INCL_DOSFILEMGR 

Idefine OPEN FILE 0x01 
Idefine CREATE_FILE 0x10 
Idefine FILE ARCHIVE 0x20 
Idefine FILEjxiSTS 0PEN_FILE 
Idefine FILE N0EXISTS CREATE_FILE 
Idefine DASD FLAG 0 
Idefine INHERIT 0x80 
Idefine WRITE THRU 0 
Idefine FAIL FLAG 0 
Idefine SHARE FLAG 0x10 
Idefine ACCESS JLAG 0x02 

Idefine FILE NAME “test.dat" 

Idefine FILE_SIZE 8O0L 

Idefine FILE ATTRIBUTE FILE.ARCHIVE 

Idefine RESERVED 0L 

HFILE FileHandle; 

USH0RT Wrote; 

USHORT Action; 

PUSHORT Local 

PSZ FileData[100] ; 

USHORT rc; 


Action = 2; 

strcpy(FileData, "Data..."); 
i f ( ! DosOpen ( F I LE_NAME , / * 

&FiTeHandle, /* 

&Action, /* 

FILE_SIZE, /* 

FILE_ATTRIBUTE, /* 

FILE EXISTS | FILE NOEXISTS, 
DASD~FLAG [ INHERIT j 
WRITE THRU | FAIL_FLAG ! 
SHARE_FLAG | ACCESS_FLAG, 
RESERVED)) /* 

i f ( I DosWri te (Fi 1 eHandl e, /* 

(PVOID) FileData, /* 

sizeof (FileData) , /* 

&Wrote)) /* 

rc * DosChgFi 1 ePtr(Fi 1 eHandl e, /* 

MOVE DIST, /* 

FILEJEG, /* 

&Local ) ; /* 


File path name */ 

File handle */ 

Action taken */ 

File primary allocation */ 

File attribute */ 

/* Open function type */ 
/ie Open mode of the file */ 


Reserved (must be zero) */ 
File handle */ 

User buffer */ 

Buffer length */ 

Bytes written */ 

File handle */ 

Distance to move in bytes */ 
Method of moving */ 

New pointer location */ 
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DosCLIAccess - 
Request CLI/STI Privilege 


This call requests I/O privilege for disabling and enabling interrupts. Access to ports must be granted 
with Dos Port Access. 


DosCLIAccess ( ) 


Parameters 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO.ERROR 

Remarks 

Applications that only use CLI/STI in IOPL segments must request CLI/STI privilege from the operating 
system. 

Applications that use IN/OUT instructions to I/O ports must request I/O privilege with DosPortAccess. 

(See “DosPortAccess — Request Port Access" on page 2-233 for more detail). Request for port access 
also grants CLI/STI privilege from the operating system. 

C Language 

#define 1NCL_D0SDEVICES 
USHORT rc « DosCLIAccess (VOID) ; 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosCLIAccess: FAR 
INCL_DOSDEVICES EQU 1 

CALL DosCLIAccess 

Returns WORD 

Example 

This example requests I/O privilege for disabling and enabling interrupts. 

Idefine INCL_DOSDEVICES 

USHORT rc; 

rc a DosCLIAccessQ; /* Request I/O privilege */ 
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FAPI 


DosClose - 
Close File Handle 


This call closes a handle to a file, pipe, or device. 


DosClose (FileHandle) 


Parameters 

FileHandle ( HFILE ) - input 

Handle returned by a previous DosOpen, DosMakeNmPipe, or DosMakePipe call. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOT_FOUND 

5 ERROR_ACCESS_DENIED 

6 ERRORJNVALIDJHANDLE 

Remarks 

Issuing DosClose with the handle to a file closes a handle to a file, pipe, or device. 

If one or more additional handles to a file have been created with DosDupHandle, the directory is not 
updated and all internal buffers are not written to the medium until DosClose has been issued for the 
duplicated handles. 

Closing a handle to a device causes the device to be notified of the close, if appropriate. 

Named Pipe Considerations 

DosClose closes a named pipe by handle. When all handles referencing one end of a pipe are closed, 
the pipe is considered broken. 

If the client end closes, no other process can re-open the pipe until the serving end issues a 
DosDisConnectNmPipe followed by a DosConnectNmPipe. 

If the server end closes when the pipe is already broken, it is deallocated immediately; otherwise, the 
pipe is not deallocated until the last client handle is closed. 

C Language 

f define INCL_DOSFILEMGR 

USHORT rc = DosClose(FileHandle) ; 

HFILE FileHandle; /* File handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosClose: FAR 
INCL_DOSF]LEMGR EQU 1 

PUSH WORD FileHandle ;File handle 
CALL DosClose 

Returns WORD 
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DosClose - 
Close File Handle 


FAPI 


Example 

This example opens a file, then closes it. 

#define INCL_DOSFILEMGR 

#define OPEN FILE 0x01 
Idefine CREATE FILE 0x10 
#define FILE_ARCHIVE 0x20 
#define FILE EXISTS 0PEN_FILE 
Idefine FILE NOEXISTS CREATE_FILE 
Idefine DASD>LAG 0 
Idefine INHERIT 0x80 
Idefine WRITE THRU 0 
Idefine FAIL_FLAG 0 
Idefine SHARE FLAG GxlO 
Idefine ACCESS_FLAG 0x02 

Idefine FILE NAME "test.dat" 

Idefine FILE_SIZE 800L 

Idefine FILE_ATTRIBUTE FILE ARCHIVE 

Idefine RESERVED 0L 

HFILE FileHandle; 

USHORT Wrote; 

USHORT Action; 

PS2 Fi1eData[100] ; 

USHORT rc; 

Action « 2; 

strcpy(FileData, “Data...”); 

if (!DosOpen(FILE_NAME, /* File path name */ 

&FileHandle. /* File handle */ 

^Action, /* Action taken */ 

FILE_SIZE, /* File primary allocation */ 

FILE_ATTRIBUTE t /* File attribute */ 

FILEJXISTS | FILEJiOEXISTS. /* Open function type */ 
DASD_FLAG ' INHERIT | /* Open mode of the file */ 

WRITE THRU ! FAIL FLAG \ 

SHARE_FLAG | ACCESS.FLAG, 

RESERVED)) /* Reserved (must be zero) */ 

rc = DosCl ose ( Fi 1 eHandl e) ; /* File Handle */ 
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DosCloseQueue - 
Close Queue 


This call closes the queue in use by the requesting process. 


DosCloseQueue (QueueHandle) 


Parameters 

QueueHandle (HQUEUE) - input 

Handle returned from a previous DosCreateQueue or DosOpenQueue call. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

337 ERROR_QUEJNVALID_HANDLE 

Remarks 

DosCloseQueue is used to terminate further processing of a queue by the requesting process. The 
actions taken depend on whether the requestor is the owner or a writer of the queue. For all processes, 
an access count representing all DosOpenQueue calls performed is decremented. For non-owning proc- 
esses, access is terminated when this count goes to zero. For owning processes, the queue (and its ele- 
ments) are purged if the access count previously equaled zero. Other processes that have the queue 
open receive the ERROR_QUEJNVALID_HANDLE return code on their next request. 

C Language 

#define INODOSQUEUES 

USHORT rc « DosCloseQueue (QueueHandle) ; 

HQUEUE QueueHandle; /* Handle of queue */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosCl oseQueue ; FAR 
INCLJ3QSQUEUES EQU 1 

PUSH WORD QueueHandle ; Queue handle 
CALL DosCloseQueue 

Returns WORD 

Example 

This example opens a queue named special. que, then closes it. 

Idefine 1NCL_D0SQUEUES 

Idefine QUE.FIFO 0 

Idefine QUE_NAME "WQUEUESWspecial .que H 

HQUEUE QueueHandle; 

USHORT rc; 

i f ( ! DosCreateQueue (&QueueHandl e , /* 

QUE_FIF0, /* 

QUE_NAME)) /* 

rc = DosCl oseQueue(QueueHandle); /* 


Queue handle */ 

Ordering to use for elements */ 
Queue name string */ 

Queue handle */ 
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DosCloseSem - 
Close System Semaphore 


This call closes a handle to a system semaphore, obtained with a DosCreateSem or DosOpenSem 
request. 


DosCloseSem (SemHandle) 


Parameters 

SemHandle ( HSEM ) - input 

Handle returned from a previous DosCreateSem or DosOpenSem call. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

102 ERROR_SEM_IS_SET 

Remarks 

DosCloseSem is issued to close a handle to a system semaphore. When all processes that obtained 
handles to the semaphore with DosCreateSem or DosOpenSem requests have issued DosCloseSem, the 
semaphore is deleted and must be redefined by the next user with a call to DosCreateSem. 

If a process has created a nonexclusive system semaphore and terminates while the semaphore is open, 
the system closes the handle to the semaphore that was returned by DosCreateSem. If the process is 
currently holding the semaphore when it terminates, OS/2 clears the semaphore and returns 
ERROR_SEM_OWNER_DIED to the next thread that gets the resource because of a DosSemRequest call. 
This error message alerts the holder of the semaphore that the semaphore owner may have ended 
abnormally; consequently, the resource is in an indeterminate state. The thread should take appropri- 
ates steps to protect the integrity of the resource. Upon completion of cleanup activity, the thread can 
release the semaphore by calling DosSemClear. This call resets the error condition flagged in the 
semaphore data structure and makes the semaphore available to the next user of the resource. The 
semaphore remains available to all processes that obtained handles to it with DosOpenSem requests 
until they call DosCloseSem to release the semaphore handies. 

If a process has created an exclusive system semaphore and terminates while the semaphore is open, 
ownership of the semaphore is transferred to the thread executing any exit list routines. If no exit list 
routines have been identified to the system with DosExitList, the system closes the handle to the 
semaphore. 

C Language 

#define I NCL_D0$ SEMAPHORES 
USHORT rc = DosCloseSem (SemHandle) ; 

HSEM SemHandle; /* Semaphore handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosCloseSem; FAR 
INCLJ30SSEMAPHORES EQU 1 

PUSH DWORD SemHandle ; Semaphore handle 
CALL DosCloseSem 

Returns WORD 
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DosCloseSem - 
Close System Semaphore 


Example 

This example creates a semaphore named timeout.sem, then closes it. 

Idefine INCL_DOSSEMAPHORES 


Idefine SEM_OWKERSHIP 0 

Idefine SEMJAME ,, \\$EM\\timeout.sem ,, 


HSEM SemHandle; 

USHORT rc; 

if ( ! OosCreateSetn ( SEM_OWNERSH I P , 
&SemHandle, 
SEMJJAME)) 

rc » DosCloseSem (SemHandle); 


/* Indicate ownership */ 

/* Semaphore handle */ 

/* Semaphore name string ie/ 
/ie Semaphore handle */ 


The following example illustrates the serialization of access to a shared resource between threads of the 
same process. The program creates a nonexclusive system semaphore named resource.sem, requests 
access to the semaphore, clears it, and finally closes the semaphore. For an illustration of notification of 
events, see the example given in DosOpenSem, DosSemSet, or DosSemWait. 

Idefine INCLJ)OSSEMAPHORE$ 
linclude <os2.h> 

Idefine SEM_NAME M \\SEM\\resource.sem M /ie Semaphore name */ 

Idefine TIMEOUT 150QL /ie Timeout (in milliseconds) ie/ 


main() 

{ 

HSEM SemHandle; 

USHORT rc; 

/ie Note; the semaphore could have been created by another ie/ 

/ie thread. ie/ 

DosCreateSem(CSEM_PUBLlC, /ie Ownership - nonexclusive ie/ 

SSemHandle, /ie Semaphore handle (returned) */ 

SEMJIAME); /ie Semaphore name ie/ 

if(!(rc - DosSemRequest (SemHandle, /* Semaphore Handle */ 

TIMEOUT))) /ie Timeout Period ie/ 

{ 

/ie Semaphore obtained; resource may now be used, ie/ 

/ie Clear the semaphore after using resource. ie/ 
i f (DosSemCl ear (SemHandl e) ) 

{ 

/ie Semaphore exclusively owned by another process — ie/ 

/ie cannot clear now. ie/ 

} 

> 

el se 

{ 

/* Semaphore not obtained: error processing (i.e. switch on rc) */ 

} 

/ie Semaphore no longer needed; close it ie/ 
i f (DosCl oseSem(SemHandl e) ) 

{ 

/ie Semaphore is still set — cannot close now ie/ 

} 
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DosConnectNmPipe - 
Connect Named Pipe 


This call is Issued by the server process and enables the named pipe to be opened by a client. 


DosConnectNmPipe (Handle) 


Parameters 

Handle ( HPIPE ) - input 

Handle of the named pipe that is returned by DosMakeNmPipe. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

95 ERRORJNTERRUPT 

109 ERROR_BROKEN_PIPE 

230 ERROR_BAD_PIPE 

233 ERROR_PIPE_NOT_CONNECTED 

Remarks 

The server process, which creates the named pipe with DosMakeNmPipe, prepares the pipe so that it can 
accept a DosOpen from a client. To prepare the pipe for its first client, the server issues 
DosConnectNmPipe. To prepare the pipe for the next client, the server issues DosDisConnectNmPipe 
followed by DosConnectNmPipe. 

When DosConnectNmPipe returns, the pipe is in a listening state. A DosOpen to a pipe that is not in a 
listening state fails. A client can determine the pipe’s state by issuing DosPeekNmPipe. 

If the client end of the pipe is currently open, DosConnectNmPipe returns immediately and has no effect. 

If the client end is not open, DosConnectNmPipe either waits until it is open (if blocking mode is set) or 
else returns immediately with ERROR_PIPE_NOT_CONNECTED (If non-blocking mode is set). In the case 
where ERROR_PIPE_NOT_CONNECTED is returned, the pipe enters a listening state, permitting a client to 
issue a successful DosOpen. 

If the pipe has been closed by a previous client but is not disconnected by the server, DosConnectNmPipe 
always returns ERROR_BROKEN_PIPE. Multiple DosConnectNmPipe calls can be issued in non-blocking 
mode; the first one puts the pipe into a listening state (if it is not already open or closing), and subsequent 
ones simply test the pipe state. 

If DosConnectNmPipe is called by the client end of the pipe, ERRORJ3AD_PIPE is returned. If the wait (in 
blocking mode only) for the client open is interrupted, the ERRORJNTERRUPT is returned. 

C Language 

#define INCLJMSNMPIPES 

USHORT rc - DosConnectNmPipe (Handle) ; 

HPIPE Handle; /* Pipe handle */ 

USHORT rc; /* return code */ 
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DosConnectNmPipe - 
Connect Named Pipe 


Assembler Language 

EXTRN DosConnectNmPipe: FAR 
INCL_DOSNMPIPES EQU 1 

PUSH WORD Handle ;Pipe handle 

CALL DosConnectNmPipe 

Returns WORD 
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DosCopy - 
Copy File 


This call copies the specified file or subdirectory to the target file or subdirectory. 


DosCopy (SourceName, TargetName, OpMode, Reserved) 


Parameters 

SourceName (PSZ) - input 

Address of the ASCIIZ path name of the source file, subdirectory, or character device. Global file 
name characters are not allowed. 

TargetName (PSZ) - input 

Address of the ASCIIZ path name of the target file, subdirectory, or character device. Global file 
name characters are not allowed. 

OpMode ( USHORT) - input 

Word-length bit map that defines how the DosCopy function is done. 

Bit Description 

15-2 Reserved and must be set to zero. 

1 0 = Replace the target file with the source file. 

1 = Append the source file to the target file’s end of data. This is ignored when copying 

a directory or if the target file doesn't exist. 

0 0 = Do not copy the source file to the target if the file name already exists within the 

target directory. If a single file is being copied and the target already exists, an error is 
returned. 

1 = Copy the source file to the target even if the file name already exists within the 
target directory. 

Reserved (ULONG) - input 

Reserved, must be set to zero. 


rc ( USHORT) - return 

Return code descriptions are: 


0 

NO_ERROR 

2 

ERROR_FILE_NOT_FOUND 

3 

ERROR_PATH_NOT_FOUND 

5 

ERROR_ACCESS_DENIED 

26 

ERROR_NOT_DOS_DISK 

32 

ERROR_SHARING_VIOLATION 

36 

ERROR_SHARING~BUFFER EXCEEDED 

87 

ERRORJNVALID.PARAMETER 

108 

ERROR_DRIVE_LOCKED 

206 

ERROR_FILENAME_EXCED_RANGE 

267 

ERROR_DIRECTORY 

Remarks 



DosCopy copies all files and subdirectories in the source path to the target path. Global file name char- 
acters are not allowed in source or target names. The source and the target may be on different drives. 
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DosCopy - 
Copy File 


In the event of an I/O error, DosCopy takes the following actions before It terminates: 

• If the source name is that of a subdirectory, the file being copied at the time of the error is deleted 
from the target path. 

• if the source name is that of a file to be replaced, the file is deleted from the target path. 

• If the source name is that of a file to be appended, the target file is resized to its original size. 

Read-only files cannot be replaced by a DosCopy request. If OpMode bit flagO is set to 1 and read-only 
files exist in the target, an attempt to replace them with files from the source returns an error. 

File attributes are always copied from the source to the target; however extended attributes (EAs) are not 
copied in every case. DosCopy copies EAs from the source to the target when creating a file or directory 
or when replacing an existing file on the target. However, it does not copy them when appending an 
existing file or when copying files to an existing directory on the target. 

If a device name is specified as the target, the source name must be a file, not a directory. When the 
request is issued, OpMode bit flags 0 and 1 are ignored. 

DosQSysInfo is called by an application during initialization to determine the maximum path length 
allowed by OS/2. 


C Language 

Idefine INCL.DOSFILEMGR 

USHORT rc = DosCopy (SourceName, TargetName, OpMode, 0); 


PSZ 

SourceName; 

/* Source path name */ 

PSZ 

TargetName; 

/* Target path name */ 

USHORT 

OpMode; 

/* Operation mode */ 

ULONG 

0; 

/* Reserved (must be zero) */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosCopy: FAR 


INCL.DOSFILEMGR EQU 1 


PUSH® 

ASCI IZ 

SourceName 

;Source path name string 

PUSH® 

ASCI IZ 

TargetName 

;Target path name string 

PUSH 

WORD 

OpMode 

; Operation mode 

PUSH 

CALL 

DWORD 

DosCopy 

0 

;Reserved (must be zero) 


Returns WORD 
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DosCreateCSAIias - fapi 

Create CS Alias 


This call creates a code segment alias descriptor for a data segment passed as input. 


DosCreateCSAIias (DataSelector, CodeSelector) 


Parameters 

DataSelector (SEL) - input 
Data segment selector. 

CodeSelector ( PSEL ) - output 

Address where the selector of the code segment alias descriptor is returned. 

rc {(JSHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

Remarks 

A selector returned by a call to DosAllocSeg with no sharing options specified can be used as the data 
segment specified with DosCreateCSAIias. The selector is valid for DS, ES, FS, GS, or SS registers. (The 
FS and GS registers only exist on the 80386 processor.) 

A CS alias segment must be exclusively accessible by the process and cannot be a huge segment. 
Selectors of shared memory segments and dynamically linked global data segments cannot be used as 
input for DosCreateCSAIias. 

The code segment selector returned by DosCreateCSAIias is valid for CS. If a procedure is stored in the 
data segment, it can be called using the CS alias. The procedure may be called from privilege level 3 or 
I/O privilege level. 

Use DosFreeSeg to free a CS alias selector created with DosCreateCSAIias. Procedures in the segment 
can continue to be referenced if the data selector for the aliased segment is passed to DosFreeSeg, 
because the CS alias selector is not affected. Once both selectors have been passed to DosFreeSeg, the 
segment is deallocated. 

Family API Considerations 

The returned selector is the segment address of the allocated memory. When the returned selector or 
the original selector is freed, OS/2 immediately deallocates the block of memory. 

C Language 

fdefine INCl.DOSMEMMGR 


USHORT rc » DosCreateCSAl i as (DataSelector, CodeSelector); 


SEL 

DataSelector; 

/* Data segment selector */ 

PSEL 

CodeSelector; 

/* Code segment selector (returned) */ 

USHORT 

rc; 

/* return code */ 
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FAPI 


DosCreateCSAIias - 
Create CS Alias 


Assembler Language 

EXTRN DosCreateCSAIias: FAR 

INCLJ30SMEMMGR EQU 1 

PUSH WORD DataSelector ;Data segment selector 

PUSHO WORD CodeSelector ;Code segment selector (returned) 

CALL DosCreateCSAl i as 

Returns WORD 

Example 

This example requests a block of memory (data segment) then requests a descriptor of the segment 
marking it as a code segment. 

Idefine INCLJOSMEWGR 

Idefine NUMBERJ)FJYTE$ 120 
#def i ne ALLOC JLAG SEG_GETTABLE 

SEL CodeSel ; 

SEL Selector; 

USHORT rc; 

1 f ( ! OosAl 1 ocSeg ( NUMB ER_0F_B YTES . 

SSelector* 

ALLOC_FLAG) ) 

rc = DosCreateCSAIias (Selector* 

&CodeSel ) ; 


/* # of bytes requested */ 
/* Selector allocated */ 

/* Allocation flags */ 

/is Data segment selector */ 
/* Code segment selector */ 
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DosCreateQueue - 
Create Queue 


This call creates a queue owned by a creating process. 


DosCreateQueue (RWHandle, QueuePrty, QueueName) 


Parameters 

RWHandle ( PHQUEUE ) - output 

Address of read/write handle of the queue. The handle is used by the requestor on return. 

QueuePrty (USHORT) - input 

Values that indicate the priority ordering algorithm to use for elements placed in the queue. 

Value Definition 

0 FIFO queue 

1 LIFO queue 

2 Priority queue (sender specifies priority zero to 15). 

QueueName ( PSZ ) - input 

Address of the name of the queue. The name string that specifies the name for the queue must 
include \QUEUES\ as the first element of the path. For example, \QUEUES\RETRIEVE\CONTROL.QUE 
is a valid queue name. The same name must be specified when calling DosOpenQueue for the 
process that adds elements to the queue. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

332 ERROR_QUE_DUPLICATE 

334 ERROR_QUE_NO_M EMORY 

335 ERROR_QUEJNVALID_NAME 

336 ERROR_GUEJNVALID_PRIORITY 

337 ERROR_QUE_INVALIDJHANDLE 

Remarks 

When specifying the name for a queue, the ASCIIZ name string must include the prefix \QUEUES\. 

Issuing DosCreateQueue creates a queue that can then be accessed by the creating process. When 
another process needs to access the queue, it issues DosOpenQueue with the queue’s name. 

The process that creates the queue owns it and has queue management privileges. Only the owner can 
peek at the elements in the queue with DosPeekQueue, remove them with DosReadQueue, or purge the 
queue of all its elements with DosPurgeQueue. 

Any process that knows the queue name can open the queue after its creation with DosOpenQueue and 
place data in It with DosWrlteQueue. It can also query the number of elements in the queue with 
DosQueryQueue and terminate its access to the queue with DosCloseQueue. 

Whether a process gains access to the queue by creating or opening it, any thread in that process has 
access to the queue with equal authority. This provides the capability for multi-server queues. 

A queue ceases to exist when its owner issues DosCloseQueue. If other processes use the queue handle 
for subsequent requests after the owner has closed the queue, ERROR_QUEJNVALIDJHANDLE is 
returned. 
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DosCreateQueue - 
Create Queue 

C Language 

#define INCL_DOSQUEUES 

USHORT rc = DosCreateQueue (RWHandle. QueuePrty, QueueName); 

PHQUEUE RWHandle; /* Address to put queue handle (returned) */ 

USHORT QueuePrty; /* Ordering to use for elements */ 

PSZ QueueName; /* Pointer to queue name string */ 

USHORT rc; /* return code ief 

Assembler Language 

EXTRN DosCreateQueue: FAR 
I NCL_DOSQUEUES EQU 1 

PUSH@ WORD RWHandle ; Queue handle (returned) 

PUSH WORD QueuePrty ‘.Ordering to use for elements 

PUSH0 ASCI IZ QueueName ; Queue name string 

CALL DosCreateQueue 

Returns WORD 

Example 

This example creates a queue named special. que. 

Idefine INCL_DOSQUEUES 

Idefine QUE_FIF0 0 

Idefine QUE_NAME “\\QUEUES\\special .que” 

HQUEUE QueueHandle; 

USHORT rc; 

rc = DosCreateQueue(&QueueHandle, fie Queue handle ief 

QUE_FIF0, fie Ordering to use for elements ief 

QUE_NAME); fie Queue name string ief 
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DosCreateSem - 
Create System Semaphore 


This call creates a system semaphore used by multiple asynchronous threads to serialize their access to 
resources. 


DosCreateSem (NoExclusive, SemHandle, SemName) 


Parameters 

NoExclusive (USHORT) - input 

Indicates whether or not the process creating the semaphore wants exclusive use of the semaphore. 
The meanings for the settings of this flag are: 

Value Definition 

0 The creating process has exclusive use of the semaphore. Only threads of the creating 
process may alter the state of the semaphore with semaphore function calls. 

1 The creating process has nonexclusive use of the semaphore. Threads of other proc- 
esses, as well as those of the creating process, may alter the state of the semaphore 
with semaphore function calls. 

SemHandle (PHSYSSEM) - output 

Address of handle of the new system semaphore. 

SemName (PSZ) - input 

Address of the name of the system semaphore. A system semaphore is defined within the file 
system name space as a pseudo file; thus, a semaphore has a full path name. The ASCIIZ string 
specifying the name must include \SEM\ as the first element of the path. For example, 
\SEM\RETRIEVE\SIGNAL.SEM is a valid semaphore name. 

Although a system semaphore name takes the form of a file in a subdirectory called \SEM, this subdi- 
rectory does not exist. System semaphores and their names are kept in memory. 

If your application provides long name support for an installable file system, a semaphore name is 
not restricted to the DOS 8.3 filename format. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

87 ERROR JNVALID_PARAMETER 

100 ERROR_TOO,MANY_SEMAPHORES 

123 errorjnvaud_name 
183 ERROR_ALREADY_EXISTS 

Remarks 

A call to DosCreateSem creates a system semaphore, which can be manipulated by threads issuing 
semaphore function calls. Manipulation of a system semaphore is most often used to control access to a 
serially reusable resource. Manipulation of the semaphore is also used to signal the occurrence of an 
event to waiting threads. 

To control access to a serially reusable resource, a process creates the system semaphore with a call to 
DosCreateSem. If the users of the resource are asynchronous threads of the creating process, 
NoExclusive = 0 is specified to create an exclusive system semaphore. If the users of the resource 
include threads of other processes, NoExclusive = 1 is specified to create a nonexclusive system 
semaphore. 

DosCreateSem returns a semaphore handle used by the creating process and any of its threads to 
access the semaphore. If the semaphore is nonexclusive, a process other than the semaphore creator 
calls DosOpenSem for a handle to access the semaphore. 
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Create System Semaphore 


Ownership of the system semaphore is established by a successful DosSemRequest call. If another 
thread issues DosSemRequest while the semaphore is owned, the thread can block and wait for the 
semaphore to become available, or it can return immediately. 

After accessing the resource, the owning thread can clear the semaphore by a call to DosSemClear. If 
the semaphore is an exclusive system semaphore, it has a use count associated with it, which is incre- 
mented by DosSemRequest calls and decremented by DosSemClear calls. The semaphore is not actually 
cleared and made available to the next thread waiting to use the resource until the semaphore has been 
cleared the same number of times It has been requested. This means that exclusive system semaphores 
can be used in recursive routines. 

If a process has created a nonexclusive system semaphore and terminates while the semaphore is open, 
the system closes the handle to the semaphore that was returned by DosCreateSem. If the process is 
currently holding the semaphore when it terminates, OS/2 clears the semaphore and returns 
ERROR_SEM_OWNER_DIED to the next thread that gets the resource because of a DosSemRequest call. 
This error message alerts the holder of the semaphore that the semaphore owner may have ended 
abnormally; consequently, the resource is in an indeterminate state. The thread should take appropri- 
ates steps to protect the integrity of the resource. Upon completion of cleanup activity, the thread can 
release the semaphore by calling DosSemClear. This call resets the error condition flagged in the 
semaphore data structure and makes the semaphore available to the next user of the resource. The 
semaphore remains available to all processes that obtained handles to it with DosOpenSem requests 
until they call DosCloseSem to release the semaphore handles. 

If a process has created an exclusive system semaphore and terminates while the semaphore is open, 
ownership of the semaphore is transferred to the thread executing any exit iist routines. If no exit list 
routines have been identified to the system with DosExitList, the system closes the handle to the 
semaphore. 

In addition to controlling access to serially reusable resources, a nonexclusive system semaphore is also 
used to signal an event, such as the removal of an element from a queue, to other processes. A process 
that sets the semaphore waits for another process to clear the semaphore, signaling the event. When the 
signaling process issues a DosSemClear, any waiting threads resume execution. Calls that support 
setting and waiting upon a nonexclusive semaphore by one or more threads are DosSemSet, 
DosSemWait, DosSemSetWait, and DosMuxSemWait. 

Note: If a thread needs to signal another thread of the same process, a RAM semaphore is used. 


C Language 

Idefine INCL_DOS$EMAPHORES 


USHORT rc a DosCreateSem(NoExclusi ve, SemHandle, SemName); 


USHORT 

NoExclusive; 

/* 

PHSYSSEM 

SemHandle; 

/* 

PSZ 

SemName; 

/* 

USHORT 

rc; 

/* 


Indicate no exclusive ownership * / 
Semaphore handle (returned) */ 
Semaphore name string */ 

return code */ 


Assembler Language 

EXTRN DosCreateSem: FAR 
INCL_DOSSEMAPHORE$ EQU 1 

PUSH WORD NoExclusive ; Indicate no exclusive ownership 

PUSH? DWORD SemHandle ; Semaphore handle (returned) 

PUSH® ASCI I Z SemName Semaphore name string 

CALL DosCreateSem 

Returns WORD 
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Create System Semaphore 


Example 

This example creates a semaphore named timeout.sem. 

Idefine INCLJJOSSEMAPHORES 

Idefine SEM OWNERSHIP 0 

Idefine SEMlNAME "WSEMWtimeout.sem" 

HSEM SemHandle; 

USHORT rc; 


rc = DosCreateSem (SEM_OWNERSHIP, /* Indicate ownership */ 

SSemHandle, /* Semaphore handle */ 

SEM_NAME); /* Semaphore name string */ 

The following example Illustrates the serialization of access to a shared resource between threads of the 
same process. The program creates a nonexclusive system semaphore named resource.sem, requests 
access to the semaphore, clears it, and finally closes the semaphore. For an illustration of notification of 
events, see the example given in DosOpenSem, DosSemSet, or DosSemWait. 

Idefine INCL_DOSSEMAPHORES 
linclude <os2.h> 

Idefine SEMLNAME "WSEMWresource.sem" /* Semaphore name */ 

Idefine TIMEOUT 15O0L /* Timeout (in milliseconds) */ 


main() 

{ 

HSEM SemHandle; 

USHORT rc; 

/* Note: the semaphore could have been created by another */ 

/* thread. */ 

DosCreateSem(CSEM_PUBLIC, /* Ownership - nonexclusive */ 

&SemHandle, /* Semaphore handle (returned) */ 

SEM_NAME); /* Semaphore name */ 

if(!(rc = DosSemRequest (SemHandle, /* Semaphore Handle */ 

TIMEOUT))) /* Timeout Period */ 

{ 

/* Semaphore obtained; resource may now be used. */ 

/* Clear the semaphore after using resource. */ 
i f (DosSemCl ear (SemHandl e) ) 

{ 

/* Semaphore exclusively owned by another process -- */ 

/* cannot clear now. */ 

} 

else 

{ 

/* Semaphore not obtained: error processing (i.e. switch on rc) */ 

/* Semaphore no longer needed; close it */ 
if (Dos Cl oseSem(SemHandl e) ) 

{ 

/* Semaphore is still set — cannot close now */ 
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DosCreateThread - 
Create Another Thread of Execution 


This call creates an asynchronous thread of execution under the current process. 


DosCreateThread (PgmAddress, ThreadlDWord, NewThreadStack) 


Parameters 

PgmAddress (PFNTHREAD) - input 

Address within program module where new thread begins execution. This address must not be in an 
IOPL segment. 

ThreadlDWord (PHD) - output 

Address of thread ID of the new thread. 

NewThreadStack (PBYTE) - input 
Address of the new thread’s stack. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

8 ERROR_NOT_ENOUGH_MEMORY 

89 ERROR_NO_PROC_SLOTS 

212 ERROR_LOCKED 

Remarks 

OS/2 creates the first thread of a process when it starts the executable file. This thread is dispatched 
with a regular class priority. To start another thread of execution under the current process, the current 
thread allocates stack memory and issues DosCreateThread. Upon generation of the far call, the 
thread’s initial dispatch point is the address specified for PgmAddress. The started thread has a unique 
stack and register context and the same priority as the requesting thread. 

Note: The minimum available space on the stack for a thread calling an operating system function must 
be 4K bytes. 

A thread's stack, register context, and priority is the only information maintained by OS/2 that is specific 
to the thread. The thread shares resources with other threads of the process. Any thread in the process 
can open a file or device, and any other thread can issue a read or write to that handle. This is also true 
for pipes, queues, and system semaphores. 

The address passed as the NewThreadStack value must be the address of the highest byte in the stack. 
This value is loaded into the SS:PP registers before starting the new thread. 

A thread started with DosCreateThread terminates upon return of this call or when a DosExit is issued. 
Any thread can temporarily stop the execution of other threads in its process with DosSuspendThread, 
DosResumeThread, DosEnterCritSec, and DosExitCritSec calls. Any thread can also examine and 
change the priority at which it and other threads execute with DosGetPrty and DosSetPrty. 

Note: DosCreateThread cannot be issued from within a segment that has I/O privilege (IOPL). If the new 
thread entry point is in an IOPL code segment, a general protection fault is generated, and the 
process is terminated. 

All code segments execute at a privilege level. Segments for OS/2 applications usually execute at 
privilege level 3. However, if an application has an IOPL code segment that is executing at privi- 
lege level 2 and has to start another thread of execution, DosCallback can be issued from the IOPL 
segment to invoke a privilege level 3 segment. But before the DosCreateThread request is made, 
the IOPL segment’s stack must be resized in the privilege level 3 segment by a call to 
DosR2StackRealloc. For more information on IOPL code segments, see IBM Operating System/2 
Version 1.2 I/O Subsystems And Device Support Volume 1 . 
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DosCreateThread - 

Create Another Thread of Execution 


C Language 

Idefine INCL_DOSPROCESS 

USHORT rc » DosCreateThread (PgmAddress, ThreadIDWord, NewThreadStack); 

PFNTHREAD PgmAddress; /* Program address */ 

PTID ThreadIDWord; /* New thread ID (returned) */ 

PBYTE NewThreadStack; /* End of stack for new thread */ 

USHORT rc; /* return code */ 


Assembler Language 

EXTRN DosCreateThread: FAR 
INCL_DOSPROCESS EQU 1 

PUSH DWORD PgmAddress ; Program address 
PUSH® WORD ThreadIDWord ;New thread ID (returned) 
PUSH® OTHER NewThreadStack ;End of stack for new thread 
CALL DosCreateThread 

Returns WORD 


Example 

In this example, a second thread is started at TestRoutine with a stack size of 4096 bytes. Remember to 
compile with Stack checking disabled (-Gs). Also, threads started with DosCreateThread should not use 
some C library functions. See chapter 6 of the IBM C/2 Language Reference (version 1.1) for a dis- 
cussion of threads and the C functions _beginthread and _endthread. This example can be compiled as 
follows: 


elm -YMS -Gs example.c 

Idefine INCL D0SPR0CESS 
Idefine INCL VIO 
Idefine SLEEP_THREAD1 5000L 
Idefine SLEEP_THREAD2 1000L 
Idefine VIO HANDLE 0 
Idefine RETURN_CODE 0 

TID ThreadID; 

BYTE ThreadStackArea [4096] ; 

USHORT rc; 

VOID APIENTRY TestRoutine( ) 

{ 

USHORT r; 

/* Interval size */ 

/* String to be written */ 

/* Length of string */ 

/* Video handle */ 

/if Indicates end thread of process if/ 
/if Result code */ 


r = DosSleep(SLEEP THREAD2); 
r = Vi oWrtTTY { " . . . Thread2 
14, 

VIO HANDLE) ; 
DosEx1t(EXIT_THREAD, 

RETURN CODE) ; 

} 


main( ) 

{ 

rc = DosCreateThread ( (PFNTHREAD) TestRoutine, /if Program address if/ 

SThreadlD, /* New thread ID if/ 

&ThreadStackArea[4095]); /if End of stack for new thread it/ 
rc = DosSl eep(SLEEP_THREAD2) ; /it Interval size */ 
printf (“. . . Threadl . . . \n" ) ; 

} 


The following example shows how to suspend and resume execution of a thread within a process. The 
main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that prints 
a line and then sleeps, relinquishing its time slice to the main thread. After one iteration by Thread2, the 
main thread suspends Thread2 and then resumes it. Subsequently, Thread2 completes the remaining 
three iterations. 
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DosCreateThread - 
Create Another Thread of Execution 


#define INCL_DOSPROCESS 
linclude <os2.h> 


#define 

SEGSIZE 

4000 

/* 

Idefine 

ALLOCFLAGS 

0 

/* 

Idefine 

SLEEPSHORT 

5L 

/* 

#define 

SLEEPLONG 

75L 

/* 

#define 

RETURN CODE 

0 

/* 


Number of bytes requested in segment */ 
Segment allocation flags - no sharing */ 
Sleep interval - 5 milliseconds */ 

Sleep interval - 75 milliseconds */ 
Return code for DosExitO */ 


VOID API ENTRY Thread2() 

{ 

USHORT i ; 


/* Loop with four iterations */ 
for(i=l; i<5; i++) 

{ 

printf("In Thread2, i is now %d\n", i); 

/* Sleep to relinquish time slice to main thread */ 
DosSleep(SLEEPSHORT) ; /* Sleep interval */ 

} 

Dos Exi t ( EX I T_THREAD , /* Action code - end a thread */ 

RETURN_CODE) ; /* Return code */ 

} 


main() 

{ 

TID ThreadID; /* Thread identification */ 

SEL ThreadStackSel ; /* Segment selector for thread stack */ 

PBYTE StackEnd; /* Ptr. to end of thread stack */ 

USHORT rc; 

/** Allocate segment for thread stack; make pointer to end of stack. **/ 
/** We must allocate a segment in order to preserve segment protection **/ 
/** for the thread. **/ 

rc « DosAl 1 ocSeg (SEGS I2E , /* Number of bytes requested */ 

AThreadStackSel , /* Segment selector (returned) */ 

ALLOCFLAGS) ; /* Allocation flags - no sharing */ 

StackEnd = MAKEP(ThreadStack$el , SEGSIZE-1); 

/** Start Thread2 **/ 

i f (! (rc=DosCreateThread((PFNTHREAD) Thread2, /* Thread address */ 

&ThreadID, /* Thread ID (returned) */ 

StackEnd))) /* End of thread stack */ 
printf ( u Thread2 created. \n” ) ; 

/* Sleep to relinquish time slice to Thread2 */ 
i f ( ! (DosSl eep (SLEEPSHORT) ) ) /* Sleep interval */ 

printf ("Slept a little to let Thread2 execute. \n“); 

/***** Suspend Thread2, do some work, then resume Thread2 *****/ 
if(!(rc=DosSuspendThread(ThreadID))) /* Thread ID */ 

pr i ntf ( “Thread2 SUSPENDED . \n “ ) ; 

printf (“Perform work that will not be interrupted by Thread2.\n“) ; 
i f ( ! (rc=DosResumeThread(ThreadID)) ) /* Thread ID */ 

printf ("Thread2 RESUMED. \n“); 
printf ("Now we may be interrupted by Thread2.\n"); 

/* Sleep to allow Thread2 to complete */ 

DosSl eep(SLEEPLONG); /* Sleep interval *1 

} 
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DosCwait — 

Wait for Child Termination 


This call places the current thread in a wait state until an asynchronous child process ends. When the 
process ends, its process ID and termination code are returned to the caller. 


DosCwait (ActionCode, WaitOption, ReturnCodes, Process ID Word, ProcessID) 


Parameters 

ActionCode ( USHORT) - input 

The process whose termination is being waited for. 

Value Definition 

0 The child process indicated by ProcessID. 

1 The last descendant of the child process indicated by ProcessID. 

WaitOption (USHORT) - input 

Return if no child process ends. 

Value Definition 

0 Wait if no child process ends or until no child processes are outstanding. 

1 Do not wait for child processes to end. 

ReturnCodes ( PRESULTCODES ) - output 

Address of the structure containing the termination code and the result code indicating the reason for 
the child’s termination. 

codeTerminate ( USHORT) 

The termination code furnished by the system describing why the child terminated. 

Value Definition 

0 EXIT (normal) 

1 Hard error abort 

2 Trap operation 

3 Unintercepted DosKillProcess 

codeResult (USHORT) 

Result code specified by the terminating process on its last DosExit call. 

ProcessIDWord (PPiD) - output 

Address of the process ID of the ending process. 

ProcessID (P!D) - input 

ID of the process whose termination is being waited for: 

Value Definition 

0 Any child process. 

^0 The indicated child process and all its descendants. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

13 ERROR_INVALID_DATA 

128 ERROR JAfAITJslOJSHILDREN 

129 ERROR_CHILD_NOT_COMPLETE 

184 ERROR_NO_CHILD_PROCESS 

303 ERRORJNVALID^PROCID 
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DosCwait - 

Wait for Child Termination 


Remarks 

DosCwait waits for completion of a child process, whose execution is asynchronous to that of its parent 
process. The child process is created by a DosExecPgm request with ExecFlags=2 specified. If the child 
process has multiple threads, the result code returned by DosCwait is the one passed to it by the DosExit 
request that terminates the process. 

DosCwait can also wait for the descendant processes of a child process to complete before it returns. 
However, it does not report status for descendant processes. 

To wait for all child processes and descendant processes to end, issue DosCwait repeatedly, with 
ActionCode=1 andProcesslD=0 specified, until ERROR_NO_CHILD_PROCESS is returned. The contents 
of ProcessIDWord can be examined to determine which child the termination codes are from. 


If no child processes were started, DosCwait returns with an error. If no child processes terminate, 
DosCwait can wait until one terminates before returning to the parent, or it can return immediately if it 
specifies WaitOption=1 . This parameter is used to return the result code of a child process that has 
already ended. 


C Language 

typedef struct ^RESULTCODES { /* rest */ 

USHORT codeTerminate; /* Termination Code */ 

USHORT codeResult; /* Exit Code */ 

} RESULTCCDES; 

idefine INCL_D0SPR0CE$S 

USHORT rc - DosCwait(ActionCode, WaitOption, ReturnCodes, ProcessIDWord, 

Process ID); 


USHORT 

ActionCode; 

/* 

USHORT 

WaitOption; 

/* 

PRESULTCODES 

ReturnCodes ; 

f* 

PPID 

ProcessIDWord; 

/* 

PID 

Process ID; 

/* 


Execution options */ 

Wait options */ 

Termination Codes (returned) */ 
Process ID (returned) */ 

Process ID of process to wait for */ 


USHORT 


rc; /* return code */ 


Assembler Language 

RESULTCODES struc 

resc_codeTerminate dw ? termination Code 
resc_codeResult dw ? ;Exit Code 

RESULTCODES ends 

EXTRN DosCwait: FAR 
INCL_DOSPROCESS EQU 1 

PUSH WORD ActionCode ; Execution options 

PUSH WORD WaitOption ;Wait options 

PUSH® DWORD ReturnCodes termination Codes (returned) 

PUSH® WORD ProcessIDWord ; Process ID (returned) 

PUSH WORD Process ID ; Process ID of process to wait for 

CALL DosCwai t 

Returns WORD 
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DosCwait — 

Wait for Child Termination 


Example 

This example starts a child session (the program simple.exe) and then waits for the child process's ter- 
mination. 

Idefine INCL_DOSPROCESS 


Idefine START_PROGRAM “simple.exe" 

CHAR LoadError[10Q] ; 

PSZ Args; 

PSZ Envs; 

RESULTCOOES ReturnCodes; 

USHORT Pid; 

USHORT rc; 


strcpy(Args, n -a2 -l n ); /* 

i f ( ! DosExecPgm ( LoadError , 

sizeof (LoadError) , 
EXEC_ASYNCRESULT, 

Args, 

Envs, 

&ReturnCodes, 

START_PROGRAM) ) 
rc = DosCwait (DCWA PROCESS, 

DCWW_WAIT, 

&ReturnCodes, 

&Pid, 

ReturnCodes , codeTermi nate) ; 


arguments ‘-a2' and '-1' */ 

/* Object name buffer */ 

/* Length of object name buffer */ 

/* Asynchronous/Trace flags */ 

/* Argument string */ 

/* Environment string */ 

/it Termination codes it/ 

/it Program file name it/ 

/it Execution options it/ 

/it Wait options it/ 

/it Termination codes it/ 

/it Process ID */ 

/* Process ID of process to wait for */ 
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FAPI 

DosDelete - 


Delete File 


This call removes a directory entry associated with a file name. 


DosDelete (FileName, Reserved) 

Parameters 

FileName (PSZ) - input 

Address of the name of the file to be deleted. 

DosQSysInfo is called by an application during initialization to determine the maximum path length 
allowed by OS/2. 

Reserved (ULONG) - input 

Reserved and must be set to zero. 

rc (USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOT_FOUND 

3 ERROR J>ATH_NOT_FOUND 

5 E R ROR_ACCESS_DEN I ED 

26 ERRORJMOT_DOS_DISK 

32 ERROR_SHARING_VIOLATION 

36 ERROR_SHARING_BUFFERJEXCEEDED 

87 ERRORJNVALID_PARAMETER 

206 ERROR_FILENAME_EXCED_RANGE 

Remarks 

Global file name characters are not permitted. 

A file whose read-only attribute is set cannot be deleted. To change the setting of the read-only bit, call 
DosSetFileMode. 

C Language 

Idefine INCL_DOSFILEKGR 

USHORT rc = DosDelete (FileName, Reserved); 

PSZ FileName; /* File name path */ 

ULONG 0; /* Reserved (must be zero) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosDelete: FAR 
INCLJJOSFILEMGR EQU 1 

PUSH® ASCI IZ FileName filename path name string 

PUSH DWORD 0 Reserved (must be zero) 

CALL DosDelete 

Returns WORD 
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DosDelete 
Delete File 


FAPI 


Example 

This example deletes a file in the current directory named test.dat. 

Idefine INCL_DOSFILEMGR 

Idefine FILE DELETE -test.dat” 

Idefine RESERVED GL 

USHORT rc; 

rc * DosDelete(FILE_DELETE, /* File path name */ 

RESERVED); /* Reserved (must be zero) */ 
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FAPI 


DosDevConfig - 
Get Device Configuration 


This call gets information about attached devices. 


DosDevConfig (Devicelnfo, Item, Parm) 


Parameters 

Devicelnfo (PVOID) - output 

Address of the byte-wide field containing the requested information. 

Item ( USHORT) - input 

Device information requested. 

Value Definition 

0 Number of printers attached 

1 Number of RS232 ports 

2 Number of diskette drives 

3 Presence of math coprocessor (where 0 = not present, 1 = present) 

4 PC Submodel Type ( where the return is the system submodel byte) 

5 PC Model Type ( where the return is the system model byte) 

6 Display adapter type (where 0 = monochrome mode compatible, 1 = other). 

Parm ( USHORT) - input 

Reserved for future use and should be set to zero. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

87 ERRORJNVALID_PARAMETER 

Remarks 

The system model (function 5) and submodel (function 4) information is obtained from BIOS. 

In addition, the number of devices attached in a PS/2 environment reflect only devices that are "awake". 
Devices that are "asleep" are not counted. 


C Language 

f define INCLJJOSDEVICES 

USHORT rc = DosDevConfig(Device!nfo, Item, Parm); 


PVOID 

Devicelnfo; 

/* Returned information */ 

USHORT 

Item; 

/* Item number */ 

USHORT 

Parm; 

/* Reserved */ 

USHORT 

rc; 

/* return */ 


Assembler Language 

EXTRN DosDevConfigiFAR 
INCL_DOSDEVICES EQU 1 

PUSH0 OTHER Devicelnfo Requested information (returned) 

PUSH WORD Item ;Itetn number 

PUSH WORD Parm Reserved (must be zero) 

CALL DosDevConfig 

Returns WORD 
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DosDevConfig - 
Get Device Configuration 


Example 

This example gets information about model type, monitor and coprocessor and display it. 

Idefine INCLJOSDEVICES 

Idefine MACHINE MODEL 5 
Idefine DISPLAY_TYPE 6 
Idefine FIND COPROCESSOR 3 
Idefine RESERVED OL 


BYTE Deviceinfo; 
USHORT rc; 


if(!DosDevConfig(&DeviceInfo, 

MACHINE MODEL* 
RESERVED)) 

printf( "Model Type %d "* Deviceinfo); 


/* Returned information */ 
/* Item number */ 

/* Reserved */ 


i f ( !DosDevConfig(&Devi celnfo* 
DISPLAY TYPE, 
RESERVED)) 
if (Deviceinfo) 

printf ("Color display ”); 
else 

printf ("Mono display "); 

if(lDosDevConfig(&DeviceInfo, 

FIND COPROCESSOR, 
RESERVED)) 
if (Deviceinfo) 

pri ntf( "Coprocessor 11 ) ; 
else 

printf ("No Coprocessor"); 


/* Returned information */ 
/* Item number */ 

/* Reserved */ 


/* Returned information */ 
/* Item number */ 

/* Reserved */ 


FAPI 
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fapi DosDevlOCtl - 

Performs I/O Control for Devices 


This call performs control functions on a device specified by an opened device handle. 


DosDevlOCtl (Data, ParmList, Function, Category, DevHandle) 


Parameters 

Data ( PVOID ) - input 

Address of the data area. 

ParmList (PVOID) - input 

Address of the command-specific argument list. 

Function (USHORT) - input 

Device-specific function code. 

Category (USHORT) - input 
Device category. 

DevHandle (HFILE) - input 

Device handle returned by DosOpen or a standard (open) device handle. 


rc ( USHORT) - 

return 

Return code descriptions are: 

0 

NO_ERROR 

1 

ERRORJNVALID_FUNCTION 

6 

ERROR J NVALI D_H AN DLE 

15 

ERROR J NVALI DJDRIVE 

31 

ERROR^GEN^FAILURE 

87 

ERROR J NVALI D_PARAMETER 

115 

ERROR_PROTECTION_VIOLATION 

117 

ERROR J NVALI D_CATEGORY 

119 

ERROR_BADJDRIVER_LEVEL 

163 

ERRORJJNCERTAIN_MEDIA 

165 

ERROR_MONITORS_NOT_SUPPORTED 

Remarks 



Values returned in the range hex FFOO through FFFF are user dependent error codes. Values returned in 
the range hex FEOO through FEFF are device driver dependent error codes. 

Refer to the IBM Operating System/2 Version 1.2 I/O Subsystems And Device Support Volume 1 for a 
complete listing of control functions (DevHlp calls). 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following con- 
siderations apply to DosDevlOCtl when coding for the DOS mode. 

The level of support for DosDevlOCtl is identified by category and function code with a noted restriction if 
it is not supported by DOS 2.X or DOS 3.X Functions tend to be more restrictive in lower version numbers 
of DOS. 

• Category 1 supported as follows: 

- 41 H Set Baud Rate 

- 42H Set Line Control 

- All other category 1 functions are not supported for DOS 2.X and DOS 3.X. 

• Category 2 not supported in FAPI 

• Category 3 not supported in FAPI 
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DosDevlOCtl - 

Performs I/O Control for Devices 


FAPI 


• Category 4 not supported in FAPI 

• Category 5 supported in FAPI as foilows: 

- 42H Set Frame control - supports IBM Graphics Printers only 

- 44H Set Infinite Retry - for DOS 2.X and DOS 3.X, the function is in effect only for the duration of 
the calling program 

- 46H Initialize printer 

- 62H Get Frame Control - not supported for DOS 2.X and DOS 3.X 

- 64H Get Infinite Retry 

- 66H Get Printer Status. 

• Category 6 not supported in FAPI 

• Category 7 not supported in FAPI 

• Category 8 supported in FAPI as follows: 

- 00H Lock Drive - not supported for versions below DOS 3.2 

- 01 H Unlock Drive - not supported for versions below DOS 3.2 

- 02H Redetermine Media - not supported for versions below DOS 3.2 

- 03H Set Logical Map - not supported for versions below DOS 3.2 

- 20H Block Removable - not supported for versions below DOS 3.2 

- 21 H Get Logical Map - not supported for versions below DOS 3.2 

- 43H Set Device Parameters - not supported for DOS 2.X and DOS 3.X 

- 44H Write Track - not supported for DOS 2.X and DOS 3.X 

- 45H Format Track - not supported for DOS 2.X and DOS 3.X 

- 63H Get Device Parameters - not supported for DOS 2.X and DOS 3.X 

- 64H Read Track - not supported for DOS 2.X and DOS 3.X 

- 65H Verify Track - not supported for DOS 2.X and DOS 3.X. 

• Category 9 is reserved 

• Category 10 (OAH) not supported in FAPI 

• Category 11 (OBH) not supported in FAPI. 


C Language 

f define INCL_DOSDEVICES 

USHORT rc = DosDevlOCtl (Data, ParmList, Function* Category, DevHandle); 


PVOID 

Data; 

/* Data area */ 

PVOID 

ParmList; 

/* Command arguments */ 

USHORT 

Function; 

/* Device function */ 

USHORT 

Category; 

/* Device category */ 

HFILE 

DevHandle; 

/* Specifies the device */ 

USHORT 

rc; 

lie return code */ 

Assembler Language 

EXTRN DosDevlOCtl: FAR 

INCL_DOSDEVICES EQU 1 

PUSH® OTHER 

Data 

;Data area 

PUSH® OTHER 

ParmLi st 

; Command arguments 

PUSH WORD 

Function 

; Device function 

PUSH WORD 

Category 

; Device category 

PUSH WORD DevHandle 

CALL DosDevlOCtl 

; Device handle 


Returns WORD 
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DosDevlOCtl2 - 
Performs I/O Control for Devices 


This call performs control functions on a device specified by an opened device handle. 


DosDevlOCtl2 (Data, DataLength, ParmList, ParmLIstLength, Function, Category, DevHandle) 


Parameters 

Data ( PVOID ) - input 

Address of the data area, 

DataLength ( USHORT) - input 
Length of the data buffer. 

ParmList (PVOID) - input 

Address of the command-specific argument list. 

ParmLIstLength (USHORT) - input 

Length of the command-specific argument list. 

Function (USHORT) - input 

Device-specific function code. 

Category (USHORT) - input 
Device category. 

DevHandle (HFILE) - input 

Device handle returned by DosOpen or a standard (open) device handle. 


re (USHORT) - 

return 

Return code descriptions are: 

0 

NOJERROR 

1 

ERROR_INVALID_FUNCTION 

6 

ERRORJNVALID_HANDLE 

15 

ERRORJNVALIDJDRIVE 

31 

ERRORJ3EN_FAILURE 

87 

errorjnvaTidj>arameter 

115 

ERROR_PROTECTION_VIOLATION 

117 

ERROR jnvalid_category 

119 

error_bad_driver_level 

163 

error_uncertain_media 

165 

error_monitors_notsupported 

Remarks 



Values returned in the range hex FFOO through FFFF are user dependent error codes. Values returned in 
the range hex FEOO through FEFF are device driver dependent error codes. 

Refer to the IBM Operating Sy$tem/2 Version 1.2 I/O Subsystems And Device Support Volume 1 for a 
complete listing of control functions (DevHIp calls). 

This function provides a generic, expandable IOCTL facility. 

A null (zero) value for Data specifies that this parameter is not defined for the generic IOCTL function 
being specified. A null value for Data causes the value passed in DataLength to be ignored. 

A null (zero) value for ParmList specifies that this parameter is not defined for the generic IOCTL function 
being specified. A null value for ParmList causes the value passed in ParmListLength to be ignored. 

The kernel formats a generic IOCTL packet and call the device driver. Since VI. 0 and VI. 1 device drivers 
do not understand generic IOCTL packets with DataLength and ParmListLength, the kernel does not pass 
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DosDevlOCtl2 - 

Performs I/O Control for Devices 


these fields to the device driver. Device drivers that are marked as being level 2 or higher must support 
receipt of the generic IOCTL packets with associated length fields. 


Do not pass a non-null pointer with a zero length. 


C Language 


#define INCL.DOSDEVICES 


USHORT rc * 

DosDevI0Ctl2(Data 

, ParmList, Function, Category, DevHandle) 

PVOID 

Data; 

/* Data area */ 

USHORT 

DataLength 

/* Data area length */ 

PVOID 

ParmList; 

/* Command arguments */ 

USHORT 

ParmList Length /* Command arguments list length */ 

USHORT 

Function; 

/* Device function */ 

USHORT 

Category; 

/* Device category */ 

HFILE 

DevHandle; 

/* Specifies the device */ 

USHORT 

rc; 

/* return code */ 

Assembler Language 


EXTRN DosDevI0Ctl2:FAR 


INCL_DOSOEVICES EQU 1 


PUSH© OTHER 

Data 

;Data area 

PUSH WORD 

DataLength 

;Data area length 

PUSH© OTHER 

ParmLi st 

; Command arguments 

PUSH WORD 

ParmList Length 

; Command arguments list length 

PUSH WORD 

Function 

; Device function 

PUSH WORD 

Category 

; Device category 

PUSH WORD 

DevHandle 

; Device handle 

CALL DosDevI0Ctl2 


Returns WORD 
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DosDisConnectNmPipe - 
Disconnect Named Pipe 


This call forces a named pipe to close. 


DosDisConnectNmPipe (Handle) 


Parameters 

Handle (HPIPE) - input 

Handle of the named pipe that is returned by DosMakeNmPipe. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

109 ERROR_BROKEN_PIPE 

230 ERROR_BAD_PIPE 

Remarks 

The server process of a named pipe issues DosDisConnectNmPipe followed by DosConnectNmPipe to 
prepare the pipe for the next client. 

If the client end of the pipe is open when DosDisConnectNmPipe is issued, it is forced to close, and the 
client gets an error code on its next operation. Forcing the client end to close may cause data to be 
discarded that has not yet been read by the client. If the client end is currently closing (DosClose has 
been issued), DosDisConnectNmPipe acknowledges the close and makes the pipe available to be opened 
by the next client after a DosConnectNmPipe is issued. 

A client that gets forced off a pipe by a DosDisConnectNmPipe must issue DosClose to free the handle 
resource. Although DosDisConnectNmPipe makes the client’s handle invalid, it does not free the client’s 
handle. 

Any threads that are blocked on the pipe are awakened by DosDisConnectNmPipe. A thread blocked on 
the pipe by a DosWrite returns ERROR_BROKEN_P!PE. A thread blocked on the pipe by a DosRead 
returns BytesRead = 0, indicating EOF. 

C Language 

Idefine INCL_DOSNMPIPES 

USHORT rc = DosDisConnectNmPipe( Handle); 

HPIPE Handle; /* Pipe handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosDisConnectNmPipe: FAR 
INCL_DOSNMPIPE$ EQU 1 

PUSH WORD Handle ;Pipe handle 

CALL DosDisConnectNmPipe 

Returns WORD 
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DosDupHandle - 
Duplicate File Handle 


FAPI 


This call returns a new file handle for an open file, which refers to the same position in the file as the old 
file handle. 


DosDupHandle (OldFileHandle, NewFileHandle) 


Parameters 

OldFileHandle (HFILE) - input 
Current file handle. 

NewFileHandle (PHFILE) - input/output 

Address of a Word. On input, values and their meanings are: 

Value Definition 

FFFFH Allocate a new file handle and return it here. 

^FFFFH Assign this value as the new file handle. A valid value is any of the handles assigned to 
standard I/O, or the handle of a file currently opened by the process. 

On output, a value of FFFFH returns a value for NewFileHandle, allocated by OS/2. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

4 ERROR_TOO_MANY_OPEN FILES 

6 ERROR_!NVALID_HANDLE 

114 ERRORJNVALID_TARGET_HANDLE 

Remarks 

Duplicating the handle duplicates and ties all handle-specific information between OldFileHandle and 
NewFileHandle. For example, if you move the read/write pointer of either handle by a DosRead, 
DosWrite, or DosChgFilePtr function call, the pointer for the other handle is also changed. 

The valid values for NewFileHandle include the following handles for standard I/O, which are always 
available to the process: 

0000H Standard input 

0001 H Standard output 

0002H Standard error. 

If a file handle value of a currently open file is specified in NewFileHandle, the file handle is closed before 
it is redefined as the duplicate of OldFileHandle. Avoid using arbitrary values for NewFileHandle. 

Issuing a DosClose against a file handle does not affect the duplicate handle. 

C Language 

#define INCL.DOSFILEKGR 

USHORT rc 3 DosDupHandle(01dFileHand1e, NewFileHandle); 

HFILE OldFileHandle; /* Existing file handle */ 

PHFILE NewFileHandle; /* New file handle (returned) */ 

USHORT rc; /* return code */ 
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FAPI 


DosDupHandle - 
Duplicate File Handle 


Assembler Language 

EXTRN DosDupHandle: FAR 
INCLJOSFILEMGR EQU 1 

PUSH WORD OldFileHandle ; Existing file handle 

PUSH0 WORD NewFileHandle ;New file handle (returned) 

CALL DosDupHandle 

Returns WORD 


Example 

This example opens a file, creates a second file handle, then closes the file with the second handle. 

Idefine INCLJOSFILEMGR 

#define OPEN FILE 0x01 
Idefine CREATE_FILE 0x10 
Idefine FILE_ARCHIVE 0x20 
#define FILE EXISTS OPEN FILE 
Idefine FILEJOEXISTS CREATE_FILE 
Idefine DASD_FLAG 0 
Idefine INHERIT 0x80 
Idefine WRITE THRU 0 
Idefine FAIL.FLAG 0 
Idefine SHARE FLAG 0x10 
Idefine ACCESSJLAG 0x02 

Idefine FILE NAME “test.dat" 

Idefine FILE_SIZE 800L 

Idefine FILE_ATTRIBUTE FILE ARCHIVE 

Idefine RESERVED OL 

HFILE FileHandle; 

HFILE NewHandl e 
USHORT Wrote; 

USHORT Action; 

PSZ FileData[100]; 

USHORT rc; 

Action ** 2; 

strcpy(FileData f "Data..."); 

i f ( ! DosOpen (FI LE_NAME , /* File path name */ 

&FileHandle, /* File handle */ 

&Action, /* Action taken */ 

FILE_SIZE, /* File primary allocation */ 

F1LE_ATTRIBUTE, /* File attribute */ 

FILE EXISTS ! FILE_NOEXISTS» /* Open function type */ 

DASD_FLAG | INHERIT ! /* Open mode of the file */ 

WRITE_THRU j FAIL FLAG \ 

SHARE.FLAG ! ACCESS_FLAG, 

RESERVED)) /* Reserved (must be zero) */ 

rc = DosDupHandle(FileHandle, /* Existing file handle */ 

&NewHandle); /* New file handle if/ 
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DosEditName - 

Search for and Edit Names of File Objects 


This call edits file and subdirectory names indirectly by transforming one ASCII string into another, using 
global file name characters for editing or search operations on the string. 


DosEditName (EdltLevel, Sourcestring, EditStrfng, TargetBuf, TargetBufLen) 


Parameters 

EdltLevel ( USHORT) - input 

The level of editing semantics to use in transforming the source string. The value of EditLevel must 
be 0001 H for OS/2 Version 1.2. 

Sourcestring (PSZ) - input 

Address of the ASCIIZ string to transform. Global file name characters are specified only in the sub- 
directory or file name component of the path name and are interpreted as search characters. 

EditString (PSZ) - input 

Address of the ASCIIZ string to use for editing. Global file name characters specified in the edit 
string are interpreted as editing characters. Because only the name component of a path name is 
transformed, this string does not include the path component. 

TargetBuf (PBYTE) - output 

Address of the buffer to store the resulting ASCIIZ string in. 

TargetBufLen (USHORT) - input 

The length of the buffer to store the resulting string in. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

87 ERROR JNVALID_PARAMETER 

123 ERROR_INVALID_NAME 

Remarks 

DosEditName is used to search for and edit names of files and subdirectories. This call is typically used 
in conjunction with calls like DosMove and DosCopy, which do not permit the use of global file name 
characters, to perform repetitive operations on files. 

As an example of an editing operation, a Sourcestring of "foo.bar" specified with an EditString of "*.baz" 
results in “FOO.BAZ” being returned. In the editing process, the string is changed to uppercase. 

Global file name characters have two sets of semantics; one for searching and one for editing. If they are 
specified in Sourcestring, they are interpreted as search characters. If they are specified in EditString, 
they are interpreted as editing characters. 

Use of the OS/2 COPY utility illustrates this difference in semantics. For example, if a user enters: 
copy *.old *.new 

In the source, the acts as a search character and determines which files to return to the user. In the 
target, the functions as an editing character by constructing new names for the matched files. 

When used as search characters in Sourcestring, global file name characters simply match files and 
behave like any other search characters. They have the following meanings: 

. The has no special meaning itself but “?” gives it one. 

* The matches 0 or more characters, any character, including a blank. The matching operation 
does not cross the null character or the backslash (\), which means only the file name is matched, not 
an entire path. 
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DosEditName - 

Search for and Edit Names of File Objects 


? The "? M matches 1 character, unless what It would match is a V or the terminating null characters, in 
which case it matches 0 characters. It also doesn't cross “V\ 

Any character other than * and ? matches itself, including 
Searching is case-insensitive. 

Any file name that does not have a period (.) in it gets an implicit one automatically appended to the end 
during searching operations. For example, searching for “foo.” would return “foo”. 

When used as editing characters in EditString, global file name characters have the following meanings: 

. The V has a special meaning for editing. The in the target synchronizes pointers. It causes the 
source pointer to match a corresponding pointer to the in the target. Counting starts from the left 
of the pointers. 

? The “?” copies one character, unless what it would copy is a V\ in which case it copies 0. It also 
copies 0 characters when the end of the source string is reached. 

* The copies characters from the source to the target until it finds a source character that matches 
the character following it in the target. 

Editing is case-insensitive and case-preserving. If conflicts arise between the case of the source and 
editing string, the case of the editing string is used. For example: 

source string: "file.txt" 

editing string: M *E.TMP” 

destination string; "filE.TMP" 

copy file.txt *E.tmp -> filE.tmp 


C Language 

#define INCL_DOSFILEMGR 

USHORT rc = DosEdi tName( Edit Level , Sourcestring, EditString, TargetBuf, TargetBufLen) ; 


USHORT 

Edit Level ; 

/* 

PSZ 

SourceString; 

/* 

PSZ 

EditString; 

/* 

PBYTE 

TargetBuf; 

/* 

USHORT 

TargetBufLen; 

/* 


Level of meta editing semantics */ 
String to transform */ 

Editing string */ 

Destination string buffer */ 
Destination string buffer length */ 


USHORT rc; 


/* return code */ 


Assembler Language 

EXTRN DosEditName: FAR 
INCL_DOSFILEMGR EQU 1 


PUSH WORD Edit Level 
PUSH® ASCI 1Z Sourcestring 
PUSH® ASCI IZ EditString 
PUSH® OTHER TargetBuf 
PUSH WORD TargetBufLen 
CALL DosEdi tName 


; Level of meta editing semantics 
; String to transform 
; Editing string 

; Destination string buffer (returned) 
•.Destination string buffer length 


Returns WORD 


Chapter 2. Control Program Function Calls 2-57 



DosEnterCritSec - 

Enter Critical Section of Execution 


This call disables thread switching for the current process. 


DosEnterCritSec ( ) 


Parameters 

re ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

484 ERROR_CRITSEC_OVERFLOW 

Remarks 

DosEnterCritSec causes other threads in the process to block themselves and give up their time slice. 
After a DosEnterCritSec request is made, no dynamic link calls should be made until the corresponding 
DosExitCritSec call is completed. 

If a signal occurs, thread 1 begins execution to process the signal even though another thread in the 
process has a DosEnterCritSec active. (Thread 1 of a process is its initial thread of execution, not a 
thread created with the DosCreateThread call.) Any processing done by thread 1 to satisfy the signal 
must not include accessing the critical resource intended to be protected by the DosEnterCritSec request. 

A count is maintained of the number of times a DosEnterCritSec request is made without a corresponding 
DosExitCritSec. The count is incremented by DosEnterCritSec and decremented by DosExitCritSec. 
Normal thread dispatching is not restored until the count is 0. The outstanding DosEnterCritSec count is 
maintained in a word. If overflow occurs, the count is set to the maximum value, no operation is per- 
formed, and the request returns with an error. 

A thread can also execute code without having to give up time slices to other threads in its process if it 
requests a priority class that is higher than those of the other threads. A thread’s priority is examined 
and changed with DosGetPrty and DosSetPrty. 

C Language 

Idefine INCL_D0SPR0CE$S 

USHORT rc = DosEnterCritSec(VOID) ; 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosEnterCri tSec : FAR 
INCL_DOSPROCE$S EQU 1 

CALL DosEnterCritSec 

Returns WORD 


Example 

This example enters a section that will not be pre-empted, performs a simple task, and then exits quickly, 
fdefine INCL_DOSPROCESS 

USHORT flag; 


DosEnterCri t Sec (); 

/* 

flag « TRUE; 

/* 

DosExitCritSecO; 

/* 


Enter critical code section */ 
Perform some work */ 

Exit critical code section */ 
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fapi DosEnumAttribute - 

Enumerate the extended attributes 


This call identifies extended attributes for a specific file or subdirectory. 


DosEnumAttribute (RefType, FileRef, EntryNum, EnumBuf, EnumBufSize, 
EnumCnt, InfoLevel, Reserved) 


Parameters 

RefType ( USHORT) - input 

A value that indicates the contents of FileRef. 

Value Definition 

0 Handle of a file. 

1 ASCIIZ name of a file or subdirectory. 

FileRef ( PVOID ) - input 

Address of the handle of a file returned by a DosOpen or DosOpen2 request; or the ASCIIZ name of a 
file or subdirectory. 

EntryNum {ULONG) - input 

Ordinal of an entry in the file object’s EA list, which indicates where in the list to begin the return of 
EA information. The value 0 is reserved. A value of 1 indicates the file object’s first EA; a value of 2, 
the second; and so on. 

EnumBuf (PVOID) - output 

Address of the buffer where EA information is returned. Level 1 information is returned in the fol- 
lowing format: 

Reserved (UCHAR) 

Zero. 

cbName (UCHAR) 

Length of name excluding NULL. 

cbValue (USHORT) 

Length of value. 

szName (UCHAR) 

Variable length asciiz name. 

EnumBufSize (ULONG) - output 
Size of EnumBuf. 

EnumCnt (PULONG) - input/output 

Address of, on input, the number of EAs for which information is requested. A value of —1 requests 
information be returned for as many EAs whose information fits in EnumBuf. 

On output, the actual number of EAs for which information is returned. When this value is greater 
than 1, enumerated information is returned in a packed list. That is, information for the next EA will 
be stored adjacent to the previous one. 

InfoLevel (ULONG) - input 

Level of information required. Only the value 1 can be specified, indicating return of level 1 informa- 
tion. 

Reserved (ULONG) - input 

Reserved and must be set to zero. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

3 ERROR_PATH_NOT_FOUND 

5 ERROR_ACCESS_DENIED 
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6 ERRORJNVALIDJHANDLE 

8 ERROR_NOT_ENOUGH_M EMORY 

87 ERROR_INVALID_PARAMETER 

111 ERROR_BUFFER_OVERFLOW 

124 ERROR JNVALID_LEVEL 

206 ERROR_FILENAME_EXCED_RANGE 

Remarks 

The structure returned by DosEnumAttribute is used to calculate the size of the buffer required to hold the 
full extended attribute (FEA) information for a DosQPathlnfo or DosQFilelnfo call that actually gets the 
FEA. The size of buffer required to hold the FEA information is calculated as follows: 

One byte (for fea_Reserved) + 

One byte (for fea_cbName) + 

Two bytes (for fea_cbValue) 4- 

Value of cbName (lor the name of the EA) + 

One byte (for terminating NULL in fea_cbName) + 

Value of cbValue (for the value of the EA) 

A process can continue through a file's EA list by reissuing DosEnumAttribute with EntryNum set to the 
value specified in the previous call plus the value returned in EnumCnt. 

DosEnumAttribute does not control the specific ordering of EAs; it merely identifies them. Like the files 
they are associated with, extended attributes can have multiple readers and writers. If a file is open in a 
sharing mode that allows other processes to modify the file's EA list, calling DosEnumAttribute repet- 
itively to back up to an EA's position may return inconsistent results. For example, it is possible for 
another process to edit the EA list with DosSetFilelnfo or DosSetPathlnfo between calls by your process 
to DosEnumAttribute. Thus, the EA returned when EntryNum is 11 for the first call may not be the same 
EA returned when EntryNum is 11 for the next call. 

To prevent the modification of EAs between calls to DosEnumAttribute for a specified file handle or file 
name, the caller must open the file in deny-write sharing mode before it calls DosEnumAttribute. If a 
subdirectory name is specified, modification by other processes is not a concern, because no sharing is 
possible. 

For RefType = 1, the EAs returned are current only when the call was made, and they may have been 
changed by another thread or process in the meantime. 

C Language 

typedef struct _DENA1 { 

UCHAR reserved; 

UCHAR cbName; 

USHORT cbValue; 

UCHAR szName[l] ; 

} DENA1; 

Idefine INCL_D0SF I LEMGR 

USHORT rc c DosEnumAttribute (RefType, FileRef, EntryNum, EnumBuf, 

EnumBufSize, EnumCnt, InfoLevel, Reserved); 

/* Type of reference */ 

/* Handle or Name */ 

/* Starting entry in EA list */ 

/* Data buffer */ 

/* Data buffer size */ 

/* Count of entries to return */ 

/it Level of information requested it/ 

/it Reserved (must be zero) */ 

/it return code */ it/ 


USHORT 

RefType; 

PVOID 

FileRef; 

ULONG 

EntryNum; 

PVOID 

EnumBuf; 

ULONG 

EnumBufSize 

PULONG 

EnumCnt; 

ULONG 

InfoLevel ; 

ULONG 

0; 

USHORT 

rc; 


/it level 1 info returned from DosEnumAttribute */ 


/* 0 */ 

/it length of name excluding NULL */ 

/* length of value it/ 

/it variable length ascii z name it/ 
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DENA1 struc ;leve1 1 info returned from DosEnumAttribute 

leve1_reserved db ? ;Q 

1evel_cbName db ? ; length of name excluding NULL 

1eve1_cbValue dw ? ; length of value 

level _szName db 1 dup (?) variable length ascii z name 

DENA1 ends 

EXTRN DosEnumAttribute: FAR 
INCL_DOSFILEMGR EQU 1 

PUSH WORD RefType 
PUSH® OTHER FileRef 
PUSH DWORD EntryNum 
PUSH® OTHER EnumBuf 
PUSH DWORD EnumBuf Size 
PUSH® DWORD EnumCnt 
PUSH DWORD InfoLevel 
PUSH DWORD 0 
CALL OosEnumAttribute 


;Type of reference 
; Handle or Name 
; Starting entry in EA list 
;Data buffer (returned) 

;Data buffer size 
: Count of entries to return 
; Level of information requested 
;Reserved (must be zero) 
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This call helps OS/2 applications respond to error codes (return codes) received from OS/2. 


DosErrClass (Code, Class, Action, Locus) 


Parameters 

Code (USHORT) — input 

Error code returned by an OS/2 function. 

Class ( PUSHORT) - output 

Address of the classification of an error. 

Action ( PUSHORT) — output 

Address of the action for an error. 

Locus ( PUSHORT) — output 

Address of the origin of an error. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

Remarks 

The input is a return code returned from another function call, and the output is a classification of the 
return and recommended action. Depending on the application, the recommended action could be fol- 
lowed, or a more specific application recovery could be performed. 

The following values are returned in Class, Action, and Locus: 

Class Definitions 


Value Mnemonic Description 


1 

OUTRES 

Out of resources 

2 

TEMPSIT 

Temporary situation 

3 

AUTH 

Authorization failed 

4 

INTRN 

Internal error 

5 

HRDFAIL 

Device hardware failure 

6 

SYSFAIL 

System failure 

7 

APPERR 

Probable application error 

8 

NOTFND 

Item not located 

9 

BADFMT 

Bad format for call/data 

10 

LOCKED 

Resource/data locked 

11 

MEDIA 

Incorrect media, CRC error 

12 

ALREADY 

Resource/action already taken/done/exists 

13 

UNK 

Unclassified 

14 

CANT 

Can’t perform requested action 

16 

TIME 

Timeout 
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Action Definitions 


Value 

Mnemonic 

Description 

1 

RETRY 

Retry immediately 

2 

DLYRET 

Delay and retry 

3 

USER 

Bad user input - get new values 

4 

ABORT 

Terminate in an orderly manner 

5 

PANIC 

Terminate immediately 

6 

IGNORE 

Ignore error 

7 

INTRET 

Retry after user intervention 

Locus Definitions 


Value 

Mnemonic 

Description 

1 

UNK 

Unknown 

2 

DISK 

Random access device such as a disk 

3 

NET 

Network 

4 

SERDEV 

Serial device 

5 

MEM 

Memory 


Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following con- 
siderations apply to DosErrClass when coding for the DOS mode: 

When DosErrClass is called by a family application, it returns a valid error classification for returns that 
have occurred. The classifications of a given return code may not be the same for the Family API and the 
OS/2 mode applications. 


C Language 

f define INCL_DOSMISC 

USHORT rc = DosErrClass (Code, Class, Action, Locus); 


USHORT 

Code; 

/* Error code for analysis */ 

PUSHORT 

Class; 

/* Error classification (returned) */ 

PUSHORT 

Action; 

/* Recommended action (returned) */ 

PUSHORT 

Locus; 

/* Error locus (returned) */ 

USHORT 

rc; 

/* return code */ 

Assembler Language 

EXTRN DosErrClass: FAR 

INCL.DOSMISC EQU 1 

PUSH WORD 

Code 

;Erro r code for analysis 

PUSH® WORD 

Class 

;Error classification (returned) 

PUSH® WORD 

Action 

; Recommended action (returned) 

PUSH® WORD Locus 

CALL DosErrClass 

; Error locus (returned) 


Returns WORD 
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Example 

This example attempts to delete a non-existent file. The error returned is then plugged into DosErrClass 
for more information about the error and what actions should be taken. 

#define INCL_DOSQUEUES 

#define RESERVED OL 
Idefine FI LE ^DELETE "adlkjf .dkf“ 

USHORT Error; 

USHORT Class; 

USHORT Action; 

USHORT Locus; 

USHORT rc; 

Error = DosDelete(FILE DELETE, 

RESERVED) ; 

rc = DosErrClass (Error, 

&Class, 

&Action, 

SLocus); 


/* File name path */ 

/* Reserved (must be zero) */ 
/* Error code for analysis */ 
/* Error classification */ 

/* Recommended action */ 

/* Error locus it/ 
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Enable Hard Error Processing 

This call allows an OS/2 process to receive hard error notification without generating a hard error signal. 

DosError (Flag) 

Parameters 

Flags ( USHORT) - input 

Bit field, defined in the following example (the unused high-order bits are reserved and must be set 
to zero). 

Bit Description 

15-2 Reserved, set to zero. 

1 0 = Enable exception popups. 

1 = Disable exception popups. 

0 0 = Disable hard error popups (fail requests). 

1 = Enable hard error popups. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

87 ERROR_INVALID_PARAMETER 

Remarks 

DosError allows an OS/2 process to disable user notification if a program (or untrapped numeric 
processor) exception occurs. If end user notification is disabled, and if one of these exceptions occurs, 
the process is terminated. 

Hard errors generated under a process that has issued a DosError call are failed, and the appropriate 
error code is returned. The default situation is both hard error pop-ups and exception pop-ups are 
enabled, if DosError is not issued. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restriction applies to DosError when coding for the DOS mode: 

For Flag, a value of 0000 causes all subsequent INT 24s to be failed until a subsequent call with a value of 
1 is issued. 

Note: Since INT 24 is not issued in DOS mode, this call has no effect when running in DOS mode. 

C Language 

#define INCL.DOSMISC 
USHORT rc = DosError(Flag); 

USHORT Flags; /* Action flags */ 

USHORT rc; /* return code */ 
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Assembler Language 

EXTRN DosError: FAR 
INCL_DOSMISC EQU 1 

PUSH WORD Flags ; Action flags 

CALL DosError 

Returns WORD 

Example 

This example disables hard error popups and exception popups, then re-enables them. 

Idefine 1NCL_D0SQUEUES 

#define ENABLEJXCEPT10N 2 
Idefine ENABLE HARDERROR 1 
#define DISABLE_ERRORPOPUPS 0 

Idefine ENABLE_ERRORPOPUPS ENABLE_EXCEPTION | ENABLE_HAROERROR 
USHORT rc; 

rc « DosError(DISABLE ERRORPOPUPS) ; /* Action flag */ 
rc = DosError(ENABLE_ERRORPOPUPS); /* Action flag */ 
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DosExecPgm - 
Execute Program 


This call allows a program to request that another program execute as a child process. 


DosExecPgm (ObjNameBuf, ObjNameBufL, ExecFlags, ArgPointer, EnvPointer, 
ReturnCodes, PgmPointer) 


Parameters 

ObJNameBuf (PCHAR) - output 

Address of the name of the object that contributed to the failure of DosExecPgm is returned. 

ObjNameBufL (SHORT) - input 

Length, in bytes, of the buffer described by ObjNameBuf. 

ExecFlags ( USHORT) - input 

Indicates how the program executes in relation to the requestor and whether execution is under con- 
ditions for debugging. 

Value Definition 

0 Execution is synchronous to the parent process. The termination code and result code 
are stored in the two-word structure. 

1 Execution is asynchronous to the parent process. When the child process terminates, its 
result code is discarded. The process ID is stored in the first word of the two-word struc- 
ture ReturnCodes. 

2 Execution is asynchronous to the parent process. When the child process terminates, its 
result code is saved for examination by a DosCwait request. The process ID is stored in 
the first word of the two-word structure ReturnCodes. 

3 Execution is the same as if ExecFlags=2 is specified, plus debugging conditions are 
present for the child process. 

4 Execution is asynchronous to and detached from the parent process session. When the 
detached process is started, it is not affected by the ending of the parent process. 

5 The program is loaded into storage and made ready to execute, but is not placed into 
execution until the session manager dispatches the threads belonging to the process. 

6 Execution is the same as if ExecFlag=2 is specified, with the addition of debugging con- 
ditions being present for the child process and any of its descendants. 

Some memory is consumed for uncollected result codes. Issue DosCwait to release this memory. If 
result codes are not collected, then ExecF!ags=0 or 1 should be used. 

ArgPointer (PSZ) - input 

Address of the ASCIIZ Argument strings passed to the program. These strings represent command 
parameters, which are copied to the environment segment of the new process. The convention used 
by CMD.EXE is that the first of these strings is the program name (as entered from the command 
prompt or found in a batch file), and the second string consists of parameters to the program name. 
The second ASCIIZ string is followed by an additional byte of zeros. A value of 0 for the address of 
ArgPointer means that no arguments are to be passed. 

EnvPointer (PSZ) - input 

Address of the ASCIIZ environment strings passed to the program. These strings represent environ- 
ment variables and their current values. An environment string has the following form: 

variable c val ue 

The last ASCIIZ environment string must be followed by an additional byte of zeros. 

A value of 0 for the address of EnvPointer results in the new process inheriting the environment of its 
parent process. 
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When the new process is given control, it receives: 

• A pointer to its environment segment 

• The fully qualified path name of the executable file 

• A copy of the argument strings. 

A coded example of this follows: 

eo: ASCI IZ string 1 ; environment string 1 

ASCI IZ string 2 ; environment string 2 

ASCI IZ string n ; environment string n 
Byte of 0 

po: ASCI IZ ; string of filename 

; of program to run. 

ao: ASCI IZ ; argument string 1 

ASCI IZ ; argument string 2 

Byte of 0 

The beginning of the environment segment is “eo” and “ao” is the offset of the first argument string 
in that segment. Register BX contains “ao” on entry to the target program. The address to the envi- 
ronment segment can also be obtained by issuing DosGetlnfoSeg. 

ReturnCodes ( PRESULTCODES ) - output 

Address of the structure containing the process ID or termination code and the result code indicating 
the reason for the child*s termination. This structure is also used by a DosCwait request, which 
waits for an asynchronous child process to end. 

termcodepld ( USHORT) 

For an asynchronous request, the process identifier of the child process. For a synchronous 
request, the termination code furnished by the system describes why the child terminated. 

Value Definition 

0 EXIT (normal) 

1 Hard error abort 

2 Trap operation 

3 Unintercepted DosKillProcess 

resultcode ( USHORT) 

Result code specified by the terminating synchronous process on its last DosExit call. 
PgmPointer (PSZ) - input 

Address of the name of the file that contains the program to be executed. When the environment is 
passed to the target program, this name is copied into “po” in the environment description shown 
above. 

If the ASCIIZ string appears to be a fully qualified path (contains a in the second position and/or 
contains a only the indicated drive:di rectory is searched. If the string is not a fully qualified 
path, the current directory is searched. If the file name is not found in the current directory, each 
drive:directory specification in the PATH defined in the current process* environment is searched for 
this file. Note that any extension (.XXX) is acceptable for the executable file being loaded. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

1 ERRORJNVALID_FUNCTION 

2 ERROR_FILE_NOT_FOUND 

3 E R RO R_P ATH_N OT_FOU N D 

4 ERROR_TOO_MANY_OPEN_FILES 

5 ERROR_ACCESS_DENIED 

8 ERROR_NOT_ENOUGH_MEMORY 

1 0 ERROR_BAD_ENVI RONMENT 

11 ERRORJ3AD_FORMAT 

13 ERR OR I N V ALI D _D AT A 
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26 

ERROR NOT DOS DISK 

32 

ERROR_SHARING_VIOLATION 

33 

ERRORJ.OCKVIOLATION 

36 

error_sharFng_buffer_exceeded 

89 

ERROR_NO_PROC_SLOTS 

95 

ERRORJNTERRUPT 

108 

ERROR JDRIVEJ.OCKED 

127 

ERROR PROC NOT FOUND 

180 

ERRORJNVALID_SEGMENT_N UMBER 

182 

ERROR_INVALID_ORDINAL 

188 

ERROR INVALlD_STARTING_CODESEG 

189 

ERROR_INVALID_STACKSEG 

190 

ERRORJNVALID_MODULETYPE 

191 

ERROR JNVALID_EXE_SIGNATURE 

192 

ERRORJEXE_MARKED_INVALID 

194 

ERROR_ITERATED_DATA_EXCEEDS_64k 

195 

ERROR_INVALID_MINALLOCSIZE 

196 

ERROR_DYNLINK_FROM_INVALID_RING 

198 

ERROR_INVALID_SEGDPL 

199 

ER ROR_AUT 0 DAT ASEG_EXCE E DS_64k 

201 

error!reloc_chain_xeeds_seglim 

Remarks 



The target program is located and loaded into storage if necessary. A process is created and executed 
for the target program. The new process is created with an address space separate from its parent; that 
is, a new Local Descriptor Table (LDT) is built for the process. 

The execution of a child process can be synchronous or asynchronous to the execution of its parent 
process. If synchronous execution is indicated, the requesting thread waits pending completion of the 
child process. Other threads in the requesting process may continue to run. 

If asynchronous execution is indicated, DosExecPgm returns with the process ID of the started child 
process. Specifying ExecFlags = 2 allows the parent process to issue a DosCwait request after the 
DosExecPgm request, so it can examine the result code returned when the child process terminates. If 
ExecFlags = 1 is specified, the result code of the asynchronous child process is not returned to the parent 
process. 

A child process inherits file handles obtained by its parent with DosOpen calls that indicated inheritance. 
The child process also inherits handles to pipes created by the parent process with DosMakePipe. 

Because a child process has the ability to inherit handles and a parent process controls the meanings of 
handles for standard I/O, the parent can duplicate inherited handles as handies for standard I/O. This 
permits the parent process and the child process to coordinate I/O to a pipe or a file. 

For example, a parent process can create two pipes with DosMakePipe requests. It can issue 
DosDupHandle to redefine the read handle of one pipe as standard input (0000H), and the write handle of 
the other pipe as standard output (0002H). The child process uses the standard I/O handles, and the 
parent process uses the remaining read and write pipe handles. Thus, the child process reads what the 
parent writes to one pipe, and the parent process reads what the child writes to the other pipe. 

When an inherited file handle is duplicated, the position of the file pointer is always the same for both 
handles, regardless of which handle repositions the file pointer. 

An asynchronous process started with ExecFlags = 3 or ExecFiags = 6 is provided a trace flag facility. 

This facility and the Ptrace buffer provided by DosPtrace enable a debugger to perform breakpoint debug- 
ging. DosStartSession provides additional debugging capabilities that allow a debugger to trace all proc- 
esses associated with an application running in a child session, regardless of whether the process is 
started with a DosExecPgm or a DosStartSession request. 
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A detached process is treated as an orphan of the parent process and executes in the background. Thus, 
it cannot make any VIO, KBD, or MOU calls, except within a video pop-up requested by VioPopUp. To test 
whether a program is running detached, use the following method. Issue a video call, (for example, 
VioGetAnsi). If the call is not issued within a video pop-up and the process is detached, the video call 
returns error code ERROR_VIO_DETACHED. 

Note: If the target program’s entry point is in a segment that has IOPL indicated, this causes a general 
protection fault and the process is terminated. If any dynamic link module being used by the new 
process has an initialization routine specified in a segment that has IOPL indicated, general pro- 
tection fault occurs and the process is terminated. 


Family API Considerations 

Some options operate differently in DOS mode than in OS/2 mode. Therefore, the following restrictions 
apply to DosExecPgm when coding in DOS mode: 

• ExecFlags must be set to zero. This value is not related to the PID of the program being executed. If 
ExecFlags ^ 0, DosExecPgm returns the error code ERROR_INVALID_DATA. 

• The ObjNameBuf field is used to provide additional information in the OS/2 mode environment as to 
why the DosExecPgm failed. The information is not relevant or available in DOS 2.X or DOS 3.X. 
Therefore, the buffer is filled in with blanks. 

• The ReturnCodes two-word structure is very similar to the OS/2 mode environment. The first word is 
a termination code with the following meanings: 

Value Definition 

0 Exit (normal exit and termination by call INT 21 H AH = 31H) 

1 Hard error abort 

2 Not returned 

3 Termination by Ctrl-Break. 

The second word contains the ResultCode specified by the terminating process on its DosExit call (or 
INT 21 H AH = 4CH call). 


C Language 

typedef struct _RESULTCODES { /* resc */ 

USKORT codeTerminate; /* Termination Code -or- Process ID */ 

USHORT codeResult; /* Exit Code */ 

} RESULTCODES; 


#define INCLJ30SPR0CESS 


USHORT rc * DosExecPgm (ObjNameBuf, ObjNameBuf L, ExecFlags, ArgPointer, 

EnvPointer, ReturnCodes, PgmPointer); 


PCHAR 

ObjNameBuf; 

/* 

SHORT 

ObjNameBuf L; 

/* 

USHORT 

ExecFlags; 

/* 

PSZ 

ArgPointer; 

/* 

PSZ 

EnvPointer; 

/* 

PRESULTCODES 

ReturnCodes ; 

/* 

PSZ 

PgmPointer; 

/* 

USHORT 

rc; 

/* 


Address of object name buffer (returned) */ 
Length of object name buffer */ 

Execute asynchronously/trace */ 

Address of argument string */ 

Address of environment string */ 

Address of termination codes (returned) */ 
Address of program file name */ 

return code */ 
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Assembler Language 

RESULTCODES struc 


? germination Code -or- Process ID 
? ;Exit Code 


resc_codeTernrinate dw 
resc_codeResult dw 

RESULTCODES ends 

EXTRN DosExecPgm: FAR 
INCL_DOSPROCESS EQU 1 

PUSH® OTHER ObjNameBuf 
PUSH WORD ObjNameBufL 
PUSH WORD ExecFlags 
PUSH® ASCIIZ ArgPoi nter 
PUSH® ASCIIZ EnvPointer 
PUSH® DWORD ReturnCodes 
PUSH® ASCIIZ PgmPointer 
CALL DosExecPgm 

Returns WORD 


;0bject name buffer (returned) 
; Length of object name buffer 
; Execute asynchronously/trace 
; Address of argument string 
; Address of environment string 
;Termi nation codes (returned) 

; Program file path name string 


Example 

This example starts up the program simple.exe and then waits for it to finish. Then the termination and 
return codes are printed. 

Idefine INCLJJOSPROCESS 

#define START_PROGRAM "simple. exe" 

CHAR LoadError[100] ; 

PSZ Args; 

PSZ Envs; 

RESULTCODES ReturnCodes; 

USHORT rc; 

i f ( I DosExecPgm ( LoadEr ror , 

sizeof (LoadError) , 

EXECJYNC, 

Args, 

Envs, 

&ReturnCodes , 

$TART_PROGRAM)) 

printf ("Termination Code %d Return 
ReturnCodes . codeT ermi nat e , 

ReturnCodes. codeResult) ; 


/* Object name buffer */ 

/* Length of object name buffer */ 
/* Asynchronous/Trace flags */ 

/* Argument string */ 

/ie Environment string ie/ 
fie Termination codes */ 

/ie Program file name iel 
Code %d \n", 


simple.exe 

Idefine INCL_DOSPROCESS 

Idefine RETURN.CODE 0 

main( ) 

{ 

printf("HelloI\n“); 

DosExi t (EXIT_PROCESS , /* End thread/process ie/ 

RETURN_CODE) ; /* Result code */ 

} 

The following example demonstrates how to create a process, obtain process ID information, and kill a 
process. Processl invokes process2 to run asynchronously. It obtains and prints some PID information, 
and then kills process2. 
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/* processl.c */ 

Idefine INCL_DOSPROCESS 
linclude <os2.h> 

Idefine START_PROGRAM “process2.exe" /* Program pointer */ 

main() 

{ 


CHAR 

Obj Fail [50]; 

fk Object name buffer kf 

RESULTCODES 

ReturnCodes; 

fk 

PIDINFO 

Pidlnfo; 


PID 

Parent ID; 

t* 

USHORT 

rc; 


printfC Process 1 now running. \n“); 


/irk Start a child process, kief 


if(!(DosExecPgm(ObjFail, fk 

sizeof(ObjFail), fk 

EXEC_ASYNC, fk 

NULL, fk 

NULL, fk 

&ReturnCodes, fk 

START_PROGRAM))) fk 


printf("Process2 started. \n"j; 


Object name buffer kf 
Length of obj. name buffer */ 

Execution flag - asynchronous kf 
No args. to pass to process2*/ 

Process2 inherits processl’s environment kf 
Ptr. to resultcodes struct, kf 
Name of program file kf 


fkk Obtain Process 10 information and print it kkf 
if (! (rc s OosGetPID(&PidInfo))) fk Process ID's (returned) kf 

printf(“DosGetPID: current process ID is %d; thread ID is %d; parent process ID is %d.\n\ 
Pidlnfo.pid, Pidlnfo.tid, Pidlnfo.pidParent) ; 
if(! (rc=DosGetPPID( 

ReturnCodes.codeTerminate, fk Process whose parent is wanted kf 
&ParentID))) fk Address to put parent's PID */ 

printf(“Child process ID is %d; Parent process ID is %d.\n\ 

ReturnCodes . codeTermi nate , Parent I D) ; 


fkk Terminate process2 kkf 

if (!(rc=DosKi 11 Process (DKP.PROCESSTREE, /* Action code - kill process and descendants */ 
ReturnCodes.codeTerminate))) /* PID of root of process tree */ 
printf (“Process2 terminated by processl.\n"): 

> 


/* process2.c */ 

fdefine INCL_D0SPR0CESS 
linclude <os2.h> 


/define SLEEPTIME 500L 
Idefine RETURN_C0DE 0 

mainO 

{ 

printf(“Process2 now running. \n“); 


} 


/* Sleep to allow processl to kill it */ 

DosSl eep(SLEEPTIME); /* Sleep 

DosExitfEXIT PROCESS, /* Action 

RETURN_C0DE): /* Result 


interval */ 
Code h/ 
Code */ 
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FAPI 


DosExit - 
Exit Program 


This call is issued when a thread completes executing. The current thread or process ends. 


DosExit (ActlonCode, ResuItCode) 


Parameters 

ActlonCode (USHORT) - input 

Terminates the process and all its threads. 

Value Definition 

0 The current thread ends. 

1 All threads in the process end. 

ResuItCode ( USHORT) - input 

Program’s completion code. It is passed to any thread that issues DosCwait for this process. 

Remarks 

DosExit allows a thread to terminate itself or be terminated by another thread in its process. If 
ActlonCode = 0 and the specified thread is the last thread executing in the process, or if ActionCode = 1 , 
the process terminates. 

The system can start threads on behalf of an application. Thus, if the intent of a DosExit call is to termi- 
nate the process, ActionCode = 1 should be specified to terminate all the threads belonging to the 
process. 

Do not terminate thread 1 without terminating the process. Thread 1 is the initial thread of execution, not 
a thread started by a DosCreateThread request. When thread 1 ends, any monitors or signal processing 
routines set for this process also end. To avoid unpredictable results, DosExit should be specified with 
ActionCode = 1 to ensure the process ends. 

When a process is terminating, all but one thread is terminated and that thread executes routines whose 
addresses have been specified with DosExitList. After resources have been cleaned up by the exit list 
routines, this thread and ail other resources owned by the process are released. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to DosExit when coding for the DOS mode: 

There is no thread support in DOS 3.3; therefore DosExit exits the currently executing program. 

If ActionCode = 0 this option is ignored. It is equivalent to an ActionCode = 1. 

C Language 

Idefine I NCL_D0S PROCESS 

VOID DosExit (ActionCode, ResuItCode); 

USHORT ActionCode; /* Indicates end thread or process */ 

USHORT ResuItCode; /* Result Code to save for DosCwait */ 
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DosExit - 
Exit Program 


FAPI 


Assembler Language 

EXTRN DosExit: FAR 
INCL.DOSPROCESS EQU 1 

PUSH WORD ActionCode indicates end thread or process 
PUSH WORD Result Code ; Result Code to save for DosCwait 
CALL DosExit 

Example 

In this example, the main routine starts up another program, simple.exe, and then expects a return code 
of 3 to be returned. Simple.exe sets the return code with DosExit. 
f define INCL_DOSPROCESS 

Idefine START.PROGRAM “simple.exe” 

Idefine RETURNOK 3 

CHAR LoadError[lGO] ; 

PS2 Args ; 

PSZ Envs; 

RESULTCODES ReturnCodes; 

USHORT rc; 

i f (IDosExecPgm(LoadError, 

sizeof(LoadError) , 

EXEC_SYNC, 

Args, 

Envs, 

SReturnCodes, 

START_PROGRAM) ) 

if (ReturnCodes.codeResult RETURN_0K) 
printf (“things are ok.."); 
else 

printf ("something is wrong..."); 


/* Object name buffer */ 

/* Length of object name buffer */ 
/* Asynchronous/Trace flags */ 

/* Argument string */ 

/* Environment string */ 

/* Termination codes */ 

/* Program file name */ 

/* Check result code */ 


simple.exe 

#define INCL_DOSPROCESS 

Idefine RETURN_CODE 3 

main( ) 

{ 

printf("Hello!\n n ); 

DosExit(EXIT_THREAD, /* End thread/process ★/ 

RETURN_CODE) ; /* Result code */ 


The following example shows how to suspend and resume execution of a thread within a process. The 
main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that prints 
a line and then sleeps, relinquishing its time slice to the main thread. After one iteration by Thread2, the 
main thread suspends Thread2 and then resumes it. Subsequently, Thread2 completes the remaining 
three iterations. 


2-74 Control Program Programming Reference 



FAPI 


DosExit - 
Exit Program 


Idefine INCL_D0SPR0CES$ 
linclude <os2.h> 


#define 

SEGSIZE 

4000 

fk 

Idefine 

ALLOCFLAGS 

0 

fk 

Idefine 

SLEEPSHORT 

5L 

f* 

Idefine 

SLEEPLONG 

75L 

f* 

Idef i ne 

RETURN CODE 

0 

/* 


Number of bytes requested in segment */ 
Segment allocation flags - no sharing */ 
Sleep interval - 5 milliseconds */ 

Sleep interval - 75 milliseconds */ 
Return code for DosExit () */ 


VOID API ENTRY Thread2() 

{ 

USHORT i ; 


/* Loop with four iterations */ 
for(i=l; i<5; i++) 

{ 

printf ("In Thread2, i is now %d\n“, i); 


/* Sleep to relinquish time 
DosSl eep(SLEEPSHORT) ; 

} 

DosExit (EXIT THREAD, 
RETURN.CODE); 

} 


slice to main thread ief 
fie Sleep interval ief 

fie Action code - end a thread ief 
fie Return code ief 


main() 

{ 


TID 

ThreadID; 

/* 

SEL 

ThreadStackSel ; 

/* 

PBYTE 

StackEnd; 

/* 

USHORT 

rc; 



Thread identification ief 

Segment selector for thread stack ief 

Ptr. to end of thread stack ief 


fieie Allocate segment for thread stack; make pointer to end of stack, -kief 
fieie We must allocate a segment in order to preserve segment protection ieief 
fieie for the thread, ieief 

rc = DosAl loc$eg(SE6SIZE, fie Number of bytes requested ief 

&ThreadStackSel , fie Segment selector (returned) ief 

ALLOCFLAGS) ; fie Allocation flags - no sharing ief 

StackEnd = MAKEP(ThreadStackSel , SEGSIZE-1); 

fieie Start Thread2 kief 

i f ( l (rc=DosCreateThread( (PFNTHREAD) Thread2, fk Thread address kf 

&ThreadID, fk Thread ID (returned) kf 

StackEnd))) fk End of thread stack kf 
printf ("Thread2 created. \n*'); 

fk Sleep to relinquish time slice to Thread2 kf 
if (! (DosSl eep(SLEEPSHORT))) fk Sleep interval kf 

printf (“Slept a little to let Thread2 execute. \n“); 

fkkkkk Suspend Thread2, do some work, then resume Thread2 kkkkkf 
if (I(rc=DosSuspendThread(ThreadID))) fk Thread ID kf 

printf ("Thread2 SUSPENDED. \n M ) ; 

printf (“Perform work that will not be interrupted by Thread2.\n“); 
if(! (rc=DosResumeThread(ThreadID))) fk Thread ID kf 

printf (“Thread2 RESUMED. \n M ) ; 
printf (“Now we may be interrupted by Thread2.\n") ; 

fk Sleep to allow Thread2 to complete kf 

DosSl eep(SLEEPLONG); fk Sleep interval kf 

} 
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DosExitCritSec - 

Exit Critical Section of Execution 


This call restores normal thread dispatching for the current process. 


DosExitCritSec ( ) 


Parameters 

None 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

485 ERROR_CRITSEC_UNDERFLOW 

Remarks 

A count is maintained of the number of times a DosEnterCritSec request is made without a corresponding 
DosExitCritSec. The count is incremented by DosEnterCritSec and decremented by DosExitCritSec. 
Normal thread dispatching is not restored until the count is 0. 

The outstanding DosEnterCritSec count is maintained In a word. If overflow occurs, the count is set to the 
maximum value, no operation is performed, and the request returns with an error. 

C Language 

f define INCLJ30SPR0CESS 

USHORT rc » DosExitCritSec(VOID) ; 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosExitCritSec: FAR 
INCL.DOSPROCESS EQU 1 

CALL DosExitCritSec 

Returns WORD 


Example 

This example enters a section that will not be pre-empted, performs a simple task, and then exits quickly. 
Idefine 1NCL_DO$PROCESS 


DosEnterCritSec () ; 

/* 

flag - TRUE; 

/* 

DosExitCritSecO ; 

/* 


Enter critical code section */ 
Perform some work */ 

Exit critical code section */ 
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DosExitList - 

Maintains Routine List for Process Termination 


This call maintains a list of routines that execute when the current process ends. 


DosExitList (FcnCode_Order, RtnAddress) 


Parameters 

FcnCode_Order (USHORT) - input 

Two-byte fields. The low-order byte indicates the operation being performed by DosExitList, which 
can be used to update the list of routines, or to transfer to the next address on the termination list at 
the completion of a routine. The values of the byte and their meanings are: 

Value Definition 

1 Add address to termination list. 

2 Remove address from termination list. 

3 Transfer to next address on termination list. 

The high-order byte indicates the invocation order. This value is valid only when the low-order byte 
is 1 (add an address). For the other low-order byte values, the high-order byte must be set to zero. 

The invocation order determines the order in which routines are invoked. Routines given a value of 
0 are invoked first and routines with a value of 255 are invoked last. If more than one routine is 
added with the same invocation order value, the last routine to be added is invoked first. The fol- 
lowing values are used by OS/2 components: 

Value Definition 

80H - 88H OS/2 Extended Edition Database Manager 

90H - 98H OS/2 Extended Edition Communications Manager 

AOH - A8H OS/2 Presentation Manager 

BOH OS/2 KBD component 

COH OS/2 VIO component 

DOH OS/2 IPC Queues component 

RtnAddress (PFNEXITUST) - input 

The address of a routine to be executed. This address cannot be in an IOPL segment. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

8 ERROR_NOT_ENOUGH_MEMORY 

13 ERROR_INVALID_DATA 

Remarks 

DosExitList maintains a list of addresses to routines that receive control when a process is terminated. 
These addresses must be in the address space of the terminating process. DosExitList routines perform 
clean-up operations on resources. For example, DosExitList can be used in a dynamic link library 
module to free resources and semaphores after a client program has ended. 

During DosExitList processing, the process is in a state of partial termination. All threads of the process 
are terminated, except for the one executing the routines. Ownership of any exclusive semaphores 
created by the process with DosCreateSem was transferred to the DosExitList thread, so the thread can 
access protected resources. Termination routines should be short and fail-safe, so there is minimum 
delay in completing process termination. 

Before transferring control to the termination routines, OS/2 resets the stack to its initial value. Transfer 
is by way of a JMP instruction. The first parameter on the stack (located at SS:SP+4) contains an indi- 
cator of why the process ended. The meanings of values returned are the same as those for termination 
codes returned by DosCwait or DosExecPgm requests. These values are: 

0 EXIT (normal exit) 
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DosExitList - 

Maintains Routine List for Process Termination 


1 Hard error abort 

2 Trap operation 

3 Unintercepted DosKillProcess. 

Each routine on the list receives control in numeric order by function high-order byte. For example, low 
(0) is first with high (OFFH) being last. In case of duplicate entries for the same value, the routines are 
executed in LIFO order. 

When a routine has completed its processing, it issues DosExitList with function = 3. Control is then 
transferred to the next address in the invocation order. If a routine on the list does not issue DosExitList 
at the completion of its processing, the process hangs, and OS/2 prevents termination. When all 
addresses are serviced, the process completes exiting. 

Most OS/2 system calls are valid in a DosExitList routine; however, certain functions such as 
DosCreateThread and DosExecPgm are not. Functions requested in a routine must not be higher in the 
function code order hierarchy than the invocation order specified for the routine. 

C Language 

Idefine INCL_D0SPR0CESS 

USHORT rc « DosExitList(FcnCode_Order, RtnAddress); 

USHORT FcnCode_Order; /* Function request code/Order */ 

PFNEXITLIST RtnAddress; /* Address of routine */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosExitList: FAR 
INCLJJOSPROCESS EQU 1 

PUSH WORD FcnCode_0rder ; Function request code/Order 
PUSH DWORD RtnAddress ; Address of routine 
CALL DosExitList 

Returns WORD 


Example 

In this example, TestRoutine is added to the exitlist sequence. Routines in the exitlist sequence must use 
DosExitList instead of DosExit to end. 

Idefine INCL DOSPROCESS 
Idefine INCI_VI0 
Idefine R0UTINE_0RDER OxEEOO 
Idefine VIOJiANDLE 0 

USHORT rc; 


VOID APIENTRY TestRoutine2() 
{ 

USHORT r; 


VioWrtTTY("This runs last..,\n“ t /* String to be written */ 

18, /* Length of string */ 

VIO_HANDLE); /* Video handle */ 

r - DosExitList(EXLST_EXIT, /* Function request code/order */ 

(PFNEXITLIST) TestRoutine2) ; /* Address of routine */ 

} 


main() 

{ 

rc = DosExitList(EXLST_ADD | R0UTINE_0RDER, /* Function request code/order */ 
(PFNEXITLIST) TestRoutine2) ; /* Address of routine */ 
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DosFilelO - 
Perform File I/O 


This call performs multiple locking, unlocking, seeking, and I/O operations on an opened file. 


DosFilelO (FlleHandie, CommandLlst, CommandListLen, ErrorOffset) 


Parameters 

FlleHandie ( HFILE ) - input 
The handle of the file. 

CommandLlst (PBYTE) - input 

Address of the list of entries, indicating the operations to be performed. CmdLock, Cmdllnlock, 
CmdSeek, and CmdIO operations are atomic. Thus, the completion of one operation is not 
dependent upon the completion of another operation following it in the list. Operations are per- 
formed until all are complete or until one fails. 

CmdLock 

Lock command structure. To perform iock operations on one or more regions in a file, a struc- 
ture is created that has the following format: 

Cmd ( USHORT) - input 

A value of 0 is required for a lock operation. 

LockCnt (USHORT) - input 

Number of regions in the file that are to be locked. 

TimeOut (LONG) - input 

The count in milliseconds until the requesting process is to resume execution if the 
requested locks are not available. In addition to specifying a milliseconds value, the fol- 
lowing values and their meanings may also be specified: 

Value Definition 

FFFFFFFFH Wait indefinitely until the requested locks become available. 

OQQOOOOOH Return immediately to the requesting process. 

Because the lock operation is atomic, if a lock within a CmdLock causes a time out, none of 
the other locks within the scope of CmdLock are in force. 

Lock 

Lock record structure. The CmdLock structure is followed by a series of records in the following 
format: 

Share (USHORT) - input 

Defines the type of access other processes may have to the file range being locked. Values 
and their meanings are: 

Value Definition 

0 Other processes have "No- Access" to the locked range. The current process 
has both read and write access to the locked range. A region with Share = 0 
must not overlap any other locked region. 

1 Other processes and the current process have “Read-Only" access to the 
locked range. A range locked with Share = 1 may overlap other ranges locked 
with Share = 1, but must not overlap other ranges locked with Share = 0. 

Start (ULONG) - input 

Offset into file where region to be locked starts. 

Length (ULONG) - input 

Length of region to be locked. 
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DosFilelO - 
Perform File I/O 


CmdUnlock 

Unlock command structure. To perform unlock operations on one or more regions in a file, a 
structure is created that has the following format: 

Cmd (USHORT) - input 

A value of 1 is required for an unlock operation. 

UnlockCnt ( USHORT) - input 

Number of regions in the file that are to be unlocked. 

UnLock 

Unlock record structure. The CmdUnlock structure is followed by a series of records in the fol- 
lowing format: 

Start (ULONG) - input 

Offset into file where region to be unlocked starts. 

Length (ULONG) - input 

Length of region to be unlocked. 

CmdSeek 

Seek command structure. To perform seek operations on one or more locked regions in a file, a 
structure is created that has the following format: 

Cmd ( USHORT) - input 

A value of 2 is required for a seek operation. 

Method (USHORT) - input 

Location in file whose offset is used to calculate the new position of the file pointer by 
adding to it the offset specified by Position. 

Value Definition 

0 Beginning of the file 

1 Current location of the file pointer 

2 End of the file. 

Position (LONG) - input 

The distance to move, in bytes. 

Actual ULONG - output 

New position of the file pointer. 

CmdIO 

I/O command structure. To perform I/O operations on one or more locked regions in a file, a 
structure is created that has the following format: 

Cmd (USHORT) - input 

Either of the following values are specified: 

Value Definition 

3 Read operation 

4 Write operation. 

Buffer (PBYTE) - input/output 

Address of the input or output buffer. 

BufferLen (USHORT) - input 

Number of bytes requested to be read or written. 

Actual (USHORT) — output 

Number of bytes actually transferred. 

CommandLlstLen (USHORT) - input 
The length in bytes of CommandList. 

ErrorOffset (PLONG) - output 

Address of the byte offset of the record in which the error occurred. 
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DosFilelO - 
Perform File I/O 


rc ( USHORT) - 

return 

Return code descriptions are: 

0 

NO_ERROR 

5 

E R ROR_ACCESS_DEN 1 E D 

6 

ERROR_INVALID_HANDLE 

33 

ERROR J.OCKJ/IOLATION 

36 

ERROR SHARING BUFFER EXCEEDED 

87 

ERROR JNVALID.PARAMETER 

95 

ERRORJNTERRUPT 

130 

ERROR JDIRECTACCESS_HANDLE 

131 

ERROR NEGATIVE SEEK 

132 

ERROR_SEEK_ON_DEVICE 

Remarks 



DosFilelO combines the following operations into a single request: 

• Unlocking and locking multiple file ranges 

• Changing the file position pointer 

• Performing file I/O. 

The ability to combine operations on files provides improved performance and makes DosFilelO partic- 
ularly suited to a networking environment. 

Unlike DosFileLocks, which unconditionally prevents access to only one range in a file at a time, 
DosFilelO permits multiple regions to be locked. DosFilelO also offers the option of read-only access to 
locked regions by the current process and any sharing processes. 

If another process attempts to read or write in a “No-access” region, or if any process attempts to write 
in a “Read-only” region, ERROR_ACCESS_DENIED is returned. 

A range to be locked must first be cleared of any locked subranges or overlapping ranges. If a time out 
occurs before locking can be completed, DosFitelO returns with an unsuccessful return code. The caller 
may return after the time-out period has expired without receiving an ERROR_SEM_TIMEOUT. Therefore, 
semaphore time-out values should not be used for exact timing and sequencing. 


C Language 

#def1ne INCL_DOSFILEHGR 

USHORT rc - DosFi leI0(Fi leHandl e, CommandList, CommandListLen, ErrorOffset); 


HFILE 

Fi leHandl e; 

/* File handle */ 

PBYTE 

CommandLi st ; 

/* Ptr to command buffer */ 

USHORT 

CommandListLen; 

/ * Length of command buffer */ 

PL0NG 

ErrorOffset; 

/* Ptr to command error offset */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 


EXTRN DosFi1eI0:FAR 
INCL_DOSFILEMGR EQU 1 


PUSH WORD FileHandle 
PUSHG OTHER CommandList 
PUSH WORD CommandListLen 
PUSH0 WORD ErrorOffset 
CALL DosFilelO 


; Fi 1 e handle 
; Command buffer 
; Length of command buffer 
; Command error offset (returned) 


Returns WORD 
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DosFileLocks - fapi 

Manages File Locking 


This call locks and unlocks a range in an opened file. 


DosFileLocks (FHeHandle, UnLockRange, LockRange) 


Parameters 

FHeHandle (HFILE) - input 
File handle. 

UnLockRange ( PLONG ) - input 

Address of the structure containing the offset and length of a range to be unlocked. A doubleword of 
zero indicates that unlocking is not required. 

FlleOffset (ULONG) 

The offset to the beginning of the range to be unlocked. 

RangeLength (ULONG) 

The length of the range to be unlocked. 

LockRange (PLONG) - input 

Address of the structure containing the offset and length of a range to be locked. A doubleword of 
zero indicates that locking is not required. 

FlleOffset (ULONG) 

The offset to the beginning of the range to be locked. 

RangeLength (ULONG) 

The length of the range to be locked. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERRORJNVALIDJHANDLE 

33 ERRORJ-OCK_VIOLATION 

36 ERROR_SHARINGJ3UFFER_EXCEEDED 

Remarks 

DosFileLocks provides a mechanism that allows a process to lock a region in a file for read/write access. 
The time a region is locked should be short. 

Instead of denying another process read/write access to the entire file by means of access and sharing 
modes specified with DosOpen or DosOpen2 requests, a process attempts to lock only the the range 
needed for read/write access and examines the error code returned. 

A range to be locked must first be cleared of any locked subranges or overlapping ranges. The locked 
region can be located anywhere in the file, and locking beyond end-of-file is not considered an error. 

Once a lock is successful, read/write access by another process to the specified range is denied until the 
range is unlocked. If both unlocking and locking are specified by a DosFileLocks request, the unlocking 
operation is performed first. After unlocking is completed, locking is done. 

Duplicating the handle duplicates access to any locked regions; however, access to locked regions is not 
duplicated across the DosExecPgm call. 

If a file is closed (either by a DosClose request or by a process terminating) and locks are still in effect, 
the locks are released in no defined order. 
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FAPI 


DosFileLocks - 
Manages File Locking 


Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following 
restrictions apply to DosFileLocks when coding for the DOS mode: 

• If Block = 1 is specified, an “invalid range lock list" or “invalid unlock list” error is returned. 

• NewLockIDList is not supported. 

C Language 

♦define INCL_DOSFILEMGR 

USHORT rc = DosFileLocks (FileHandle, UnLockRange, LockRange); 

HFILE FileHandle; /* File handle */ 

PLONG UnLockRange; /* UnLock range */ 

PLONG LockRange; /* Lock range */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosFileLocks: FAR 
INCL.DOSFILEMGR EQU 1 

PUSH WORD FileHandle ;File handle 

PUSH® OTHER UnLockRange ;UnLock range 

PUSH0 OTHER LockRange ;Lock range 

CALL DosFileLocks 

Returns WORD 
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DosFileLocks — 
Manages File Locking 


Example 

This example opens a file, writes some data to it, locks a block of the data, and then unlocks it. 

#define INCL_DOSFILEMGR 

Idefine OPEN FILE 0x01 
Idefine CREATE_FILE 0x10 
Idefine FILE ARCHIVE 0x20 
Idefine FILElEXI$TS OPEN FILE 
Idefine FILE NOEXISTS CREATE_FILE 
Idefine DASD_FLAG 0 
Idefine INHERIT 0x80 
Idefine WRITE THRU 0 
Idefine FAIL_FLAG 0 
Idefine SHARE_FLAG 0x10 
Idefine ACCESS JLAG 0x02 

Idefine FILE_NAME “test.dat" 

Idefine FILE SIZE 80OL 
Idefine FILE.ATTRIBUTE FILE ARCHIVE 
Idefine RESERVED 0L 
Idefine NULL_RANGE 0L 

HFILE FileHandle; 

USHORT Wrote; 

USHORT Action; 

PSZ FileData[100] ; 

USHORT rc; 

struct LockStrc 

{ 

long Offset; 
long Range; 

} Area; 


int i; 


Action = 2; 

strcpy(FileData, “Data..."); 
Area. Off set = 4; 

Area. Range = 100; 


i f ( ! DosOpen (FILE_NAME, /* 

SFileHandle, /* 

&Action, /* 

FILE SIZE, /* 

fileIattribute, /* 


FILE EXISTS ! FILEJiOEXISTS, 
DASD FLAG | INHERIT | 
WRITE_THRU ! FAIL_FLAG ! 
SHARE FLAG | ACCESS FLAG, 


RESERVED)) 

{ 

for(i=0; i<20O; ++i) 

/* 

DosWrite (FileHandle, 

/* 

FileData, 

/* 

sizeof(FileData), 

/* 

&Wrote) ; 

/* 

rc = DosFileLocks (FileHandle, 


NULL_RANGE, 



(PLONG) &Area) ; 
rc = DosFileLocks (FileHandle, 

(PLONG) &Area, 
NULL RANGE); 

} 


File path name */ 

File handle */ 

Action taken */ 

File primary allocation */ 

File attribute */ 

/* Open function type */ 
/* Open mode of the file */ 


Reserved (must be zero) */ 


File handle */ 

User buffer */ 

Buffer length */ 

Bytes written */ 

/* File handle */ 
/* Unlock range */ 
/* Lock range */ 

/* File handle */ 
/* Unlock range */ 
/* Lock range */ 


FAPI 
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FAPI 


DosFindClose - 
Close Find Handle 


This call closes the association between a directory handle and a DosFindFirst or DosFindNext directory 
search function. 


DosFindClose (DirHandle) 


Parameters 

DirHandle {HDIR) - input 

Handle previously associated with a DosFindFirst by the system, or used with a DosFindNext direc- 
tory search function. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

6 ERRORJNVALIDJHANDLE 

Remarks 

When DosFindClose is issued, a subsequent DosFindNext for the closed DirHandle fails unless an inter- 
vening DosFindFirst has been issued specifying DirHandle. 

C Language 

Idefine INCLJ)OSFILEMGR 

USHORT rc = DosFindClose(DirHandle) ; 

HDIR DirHandle; /* Directory search handle */ 

USHORT rc; /* return code */ 


Assembler Language 

EXTRN DosFindClose: FAR 

INCL_DOSFILEMGR EQU 1 

PUSH WORD DirHandle directory search handle 

CALL DosFindClose 

Returns WORD 

Example 

This example searches for a file, then closes the search. 

Idefine INCL_DOSFILEMGR 

#define SEARCH.PATTERN 

Idefine FILE_ATTRIBUTE 0 

Idefine RESERVED GL 

HDIR FindHandle; 

FindHandle = 0x0001; 

FindCount = 1; 

rc = Do s Fi ndFi rst (S EARCH_PATTERN , 

&FindHandle, 

FILE__ATTRIBUTE, 

SFindBuffer, 
sizeof(FindBuffer) » 

&FindCount, 

RESERVED); 

rc = DosFindClose(FindHandle); 


/* File pattern */ 

/* Directory search handle */ 
/* Search attribute */ 

/* Result buffer */ 

fie Result buffer length */ 

/* I of entries to find */ 

/* Reserved (must be zero) */ 
/* Directory search handle */ 


Chapter 2. Control Program Function Calls 2-85 







DosFind First - 

Find First Matching File Object 


FAPI 


This call finds the first file object or group of file objects whose name(s) match the specification. 


DosFindFirst (FileName, DirHandle, Attribute, ResuitBuf, ResultBufLen, SearchCount, 
Reserved) 


Parameters 

FileName ( PSZ ) - input 

Address of the ASCIIZ path name of the file or subdirectory to be found. The name component may 
contain global file name characters. 

DirHandle (PHDIR) - input/output 

Address of the handle associated with a specific DosFindFirst request. The values that can be speci- 
fied are: 

Value Definition 

0001 H Assign handle 1, which is always available to a process. 

FFFFH The system allocates and returns a handle. 

If on input FFFFH is specified, on output DirHandle contains the handle allocated by the system. 

The DosFindFirst handle is used with subsequent DosFindNext requests. Reuse of this handle in 
another DosFindFirst closes the association with the previous DosFindFirst and opens a new associ- 
ation. 

Attribute ( USHORT) - input 

Attribute value that determines the file objects to be searched for. 

Bit Description 

15-6 Reserved and m ust be zero. 

5 File archive 

4 Subdirectory 

3 Reserved and must be zero. 

2 System file 

1 Hidden file 

0 Read only file 

These bits may be set individually or in combination. For example, an attribute value of 0021 H {bits 5 
and 0 set to 1) indicates a read-only file that should be archived. 

If Attribute is 0, normal file entries are found. Entries for subdirectories, hidden, and system files, 
are not returned. If Attribute is set for hidden or system files, or directory entries, it is considered an 
inclusive search. All normal file entries plus all entries matching the specific attributes are returned. 
Set Attribute to hidden+system+di rectory (all three bits on) to look at all directory entries except the 
volume label. 

Attribute cannot specify the volume label. Volume labels are queried using DosQFSInfo. Attributes 
of a file are queried and set with DosQFileMode and DosSetFileMode. 

ResuitBuf (PFILEFINDBUF) - output 

Address of the structure that contains the returned directory information. The information reflects 
the last DosClose, DosBufReset, DosSetFileMode, DosSetFilelnfo, and DosSetPathlnfo calls. 

filedate ( FDATE ) 

Structure containing the date of file creation. 

Bit Description 

15-9 Year, in binary, of file creation 
8-5 Month, in binary, of file creation 

4-0 Day, in binary, of file creation. 
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filetime (FTIME) 

Structure containing the time of file creation. 

Bit Description 

15-11 Hours, in binary, of file creation 

10-5 Minutes, in binary, of file creation 

4-0 Seconds, in binary number of two-second increments, of file creation, 

fileaccessdate (FDATE) 

Structure containing the date of last access. See FDATE in filedate. 
fileaccesstime {FTIME) 

Structure containing the time of last access. See FTIME in filetime, 
writeaccessdate (FDATE) 

Structure containing the date of last write. See FDATE in filedate. 
writeaccesstime (FTIME) 

Structure containing the time of last write. See FTIME in filetime. 

filesize (ULONG) 

File size. 

fllealloc (ULONG) 

Allocated file size. 

flleattrib (USHORT) 

Attributes of the file, defined in DosSetFileMode. 
length (UCHAR) 

Length of the ASCIIZ name string, 
matchfilename (CHAR) 

ASCliZ name string for the first occurrence of FileName. 

ResultBufLen ( USHORT) - input 
Length of ResultBuf 

SearchCount (PUSHORT) — input/output 

Address of the number of matching entries requested in ResultBuf. On return, this field contains the 
number of entries placed into ResultBuf. 

Reserved (ULONG) - input 

Reserved, must be set to zero. 

rc (USHORT) - return 


Return code 

\ descriptions are: 

0 

NO.ERROR 

2 

ERROR_FILE_NOT_FOUND 

3 

ER RO R_PATH_NOT_FOU N D 

6 

ERRORJNVALID_HANDLE 

18 

ERROR_NO_MORE_FILES 

26 

ERROR_NOT_DOS_DISK 

87 

ERROR_INVALID_PARAMETER 

108 

ERROR_DRIVE_LOCKED 

111 

ERROR.BUFFER.OVERFLOW 

113 

ERROR_NO_MORE_SEARCH_HANDLES 

206 

ERROR_FILENAME_EXCED_RANGE 
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Remarks 

DosFindFirst returns directory entries (up to the number requested in SearchCount) for as many files or 
subdirectories whose names and attributes match the specification and whose information fits in 
ResultBuf. On output, SearchCount contains the actual number of directory entries returned. 

DosFindNext uses the directory handle associated with DosFindFirst to continue the search started by the 
DosFindFirst request. 

Any non-zero return code indicates no handle has been allocated, including such non-error indicators as 
ERROR_NO_MORE_FILES. 

DosQSysinfo is called by an application to determine the maximum path length allowed by OS/2. 

For programs running without the NEWFILES bit set, only 8.3 filename format names are returned. These 
names are changed to uppercase. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following 
restrictions apply to DosFindFirst when coding for the DOS mode: 

DirHandle must always equal hex 0001H or FFFFH on the initial call to DosFindFirst. Subsequent calls to 
DosFindFirst must have a DirHandle of hex 0001 H unless a DosFindClose had been issued. In this case, 
0001 H or FFFFH is allowed. 


C Language 

typedef struct _FDATE { /* fdate */ 


unsigned day : 5; 
unsigned month : 4; 
unsigned year : 7; 

} FDATE; 


/* binary day for directory entry */ 
/* binary month for directory entry */ 
/* binary year for directory entry if/ 


typedef struct _FTIME { 


/if ftime if/ 


unsigned twosecs : 5 
unsigned minutes : 6 
unsigned hours ; 5 

} FTIME; 


/if binary number of two-second increments */ 
/* binary number of minutes */ 

/if binary number of hours if/ 


typedef struct _FILEFINDBUF { /* findbuf */ 


FDATE fdateCreation; 

FTIME ftimeCreation; 

FDATE fdateLastAccess; 

FTIME ft imeLast Access; 

F0ATE fdatelastWrite; 

FTIME ftimeLastWrite; 

UL0NG cbFile; 

ULONG cbFileAlloc; 

USH0RT at tr File; 

UCHAR cchName; 

CHAR achName [CCHMAXPATHCOMP] 


/if file date of creation if/ 

/if file time of creation if/ 

/if file date of last access if/ 

/•k file time of last access if/ 

/if file date of last write */ 

/* file time of last write if/ 

/if file end of data */ 

/if file allocation */ 

/if file attribute if/ 

/* length of ASCI IZ name string */ 
/if ASCI IZ name string */ 


} FILEFINDBUF; 
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Idefine INCLJ10SFILEMGR 

USHORT rc » OosFindFirst(Fi leName, DirHandle, Attribute, ResultBuf, 

ResultBufLen, SearchCount, Reserved); 

PSZ Fi leName; /* File path name */ 

PHDIR DirHandle; /* Directory search handle */ 

USHORT Attribute; /* Search attribute *7 

PFILEFINDBUF ResultBuf; /* Result buffer */ 

USHORT ResultBufLen; /* Result buffer length * 

PUSHORT SearchCount; /* Number of entries to find */ 

ULONG 0; /* Reserved (must be zero) */ 

USHORT rc; /* return code */ 

Assembler Language 

FDATE struc 
fdate_fs dw ? 

FDATE ends 
FTIME struc 
ftime_fs dw ? 

FTIME ends 
FILEFINDBUF struc 

findbuf_fdateCreation dw (size FDATE) /2 dup (?) ;file date of creation 

findbuf_ftimeCreation dw (size FTIME) /2 dup (?) ;file time of creation 

f i ndbuf_f dateLastAccess dw (size FDATE) /2 dup (?) ;f i 1 e date of last access 

findbuf_f time Last Access dw (size FTIME)/2 dup (?) ;file time of last access 

findbuf_fdateLastWrite dw (size FDATE) /2 dup (?) ;file date of last write 

findbuf_ftimeLastWrite dw (size FTIME)/2 dup (?) ;file time of last write 

findbuf_cbFile dd ? ;file end of data 

findbuf_cbFileAlloc dd ? ;f i 1 e allocation 

findbuf^attrFile dw ? ;file attribute 

findbuf_cchName db ? ; length of ASCIIZ name string 

findbuf_achName db CCHMAXPATHCOMP dup (?) ; length of ASCIIZ name string 

FILEFINDBUF ends 

EXTRN DosFindFirst; FAR 
INCL_DOSFILEMGR EQU 1 

PUSH® ASCIIZ FileName ;File path name string 

PUSH® WORD DirHandle ; Directory search handle (returned) 

PUSH WORD Attribute ; Search attribute 

PUSH® OTHER ResultBuf ; Result buffer 

PUSH WORD ResultBufLen ; Result buffer length 

PUSH® WORD SearchCount ; Number of entries to find 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosFindFirst 

Returns WORD 
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Example 

This example searches for a file matching the pattern 'te??.dat/ 

#define INCLJJOSFILEMGR 

#define NORMAL_FILES G 
#define HIDDEN_FILES 2 
#define SEARCH PATTERN "te??.dat“ 

#def i ne FILE ATTRIBUTE NORMAL_FILES | HIDDEN FILES 
#define RESERVED OL 

HDIR FindHandle; 

FILEFINDBUF FindBuffer; 

USHORT FindCount; 

USHORT rc; 

FindHandle = 0x0001; 

FindCount * 1; 

rc = DosFi ndFi rst (SEARCH_PATTERN, 

SFindHandle, 

FILE ATTRIBUTE, 

&FindBuffer, 
si zeof (FindBuffer), 

&FindCount, 

RESERVED); 


/* File pattern is/ 

/* Directory search handle */ 
/it Search attribute */ 

/* Result buffer is/ 

/is Result buffer length is/ 

/is # of entries to find is/ 
/* Reserved (must be zero) */ 
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Find First Matching File Object with Extended Attributes 


This call finds the first file object or group of file objects whose name(s) match the specification. The 
specification can include extended attribute information associated with a file or subdirectory. 


DosFlndFlrst2 (FileName, DirHandle, Attribute, ResultBuf, ResuItBufLen, SearchCount, 
FilelnfoLevel, Reserved) 


Parameters 

FileName ( PSZ ) - input 

Address of the ASCIIZ path name of the file or subdirectory to be found. The name component may 
contain global file name characters. 

DirHandle (PHDIR) - input/output 

Address of the handle associated with a specific DosFindFirst2 request. The values that can be spec- 
ified are: 

0001 H The system assigns the handle for standard output, which is always available to a 

process. 

FFFFH The system allocates and returns a handle. 

If on input FFFFH is specified, on output DirHandle contains the handle allocated by the system. 

The DosFindFirst2 handle is used with subsequent DosFindNext requests. Reuse of this handle in 
another DosFindFirst2 closes the association with the previous DosFindFirst2 and opens a new asso- 
ciation. 

Attribute (USHORT) - input 

Attribute value that determines the file objects to be searched for. 

Bit Description 

15-6 Reserved and must be zero. 

5 File archive 

4 Subdirectory 

3 Reserved and must be zero. 

2 System file 

1 Hidden file 

0 Read only file 

These bits may be set individually or in combination. For example, an attribute value of 0021 H (bits 5 
and 0 set to 1) indicates a read-only file that should be archived. 

To look at all directory entries except the volume label, set Attribute to hidden+system+directory (all 
three bits on). Attribute cannot specify the volume label. Volume labels are queried using 
DosQFSInfo. 

If Attribute is 0, only normal file entries are found. Entries for subdirectories, hidden, and system 
files, are not returned. 

ResultBuf (PVOID) - input/output 

Address of the directory search structures for file object information levels 1 through 3. The struc- 
ture required for ResultBuf is dependent on the value specified for FilelnfoLevel. The information 
returned reflects the last DosSetFilelnfo, DosSetPathlnfo, DosClose, and DosBufReset calls. 

Level 1 Information 

ResultBuf contains the following structure, to which directory entry information is returned: 
flledate (FDATE) 

Structure containing the date of file creation. 

Bit Description 

15-9 Year, in binary, of file creation 

8-5 Month, in binary, of file creation 
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4-0 Day, in binary, of file creation, 

filetime (FTIME) 

Structure containing the time of file creation. 

Bit Description 

15-11 Hours, in binary, of file creation 

10-5 Minutes, in binary, of file creation 

4-0 Seconds, in binary number of two-second increments, of file creation, 

fileaccessdate ( FDATE ) 

Structure containing the date of last access. See FDATE in filedate. 
fileaccesstime (FTIME) 

Structure containing the time of last access. See FTIME in filetime, 
writeaccessdate (FDATE) 

Structure containing the date of last write. See FDATE in filedate. 
writeaccesstime (FTIME) 

Structure containing the time of last write. See FTIME in filetime. 

filesize (ULONG) 

File size. 

fllealloc (ULONG) 

Allocated file size. 

fileattrib (USHORT) 

Attributes of the file, defined in DosSetFileMode. 
length (UCHAR) 

Length of the ASCIIZ name string, 
matchfllename (CHAR) 

ASCIIZ name string for the first occurrence of FileName. 

Level 2 Information 

ResultBuf contains a structure similar to the Level 1 structure, with the addition of the cbList field 
inserted before the name length field of the matched file object. 

cbList (ULONG) 

On output, this field contains the length of the entire EA set for the file object. This value 
can be used to calculate the size of the buffer required to hold EA information returned 
when FilelnfoLevel = 3 is specified. 

Level 3 Information 

ResultBuf contains an EAOP structure, which has the following format: 
fpGEAList (PGEALIST) 

Address of GEAList. GEAList is a packed array of variable length “get EA" structures, each 
containing an EA name and the length of the name. 

fpFEALIst (PFEALIST) 

Address of FEAList. FEAList is a packed array of variable length “full EA” structures, each 
containing an EA name and its corresponding value, as well as the lengths of the name and 
the value. 

oError (ULONG) 

Offset into structure where error has occurred. 

On input, fpGEAList contains the address of a GEA list, which defines the attribute names whose 
values are to be returned. fpGEAList is ignored. In case of error, oError contains the offset of 
the offending GEA entry. Following is the format of the GEAList structure: 

cbList (ULONG) 

Length of the GEA list, including the length itself. 
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Find First Matching File Object with Extended Attributes 

list (GEA) 

List of GEA structures. A GEA structure has the following format: 
cbName (BYTE) 

Length of EA ASCHZ name, which does not include the null character. 

szName (CHAR) 

ASCIIZ name of EA. 

Following the EAOP structure is a structure similar to the Level 1 structure, with the addition of 
an FEAList structure inserted before the name length field for the matched file object. 

On output, this structure contains a packed set of records representing the directory entry and 
associated EAs for the matched file object. Following is the format of the FEAList structure: 

cbLIst (ULONG) 

Length of the FEA list, including the length itself, 
list (FEA) 

List of FEA structures. An FEA structure has the following format: 

Flags (BYTE) 

Bit indicator describing the characteristics of the EA being defined. 

Bit Description 

15 Critical EA. 

14-0 Reserved and must be set to zero. 

If bit 15 is set to 1 , this indicates a critical EA. If bit 15 is 0 , this means the EA is noncrit- 
ical; that is, the EA is not essential to the intended use by an application of the file with 
which it is associated. 

cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character. 
cbValue (USHORT) 

Length of EA value, which cannot exceed 64KB. 

szName (PSZ) 

ASCIIZ name of EA. 

aValue (PSZ) 

Free-format value of EA. 

Note: The szName and aValue fields are not included as part of header or include files. 
Because of their variable lengths, these entries must be built manually. 

ResultBufLen (USHORT) — input 
Length of ResultBuf. 

SearchCount (PUSHORT) - input/output 

Address of the number of matching entries requested in ResultBuf. On return, this field contains the 
number of entries placed into ResultBuf. 

FllelnfoLevel (USHORT) 

The level of file information required. A value of 1, 2, or 3 can be specified. The structures 
described in ResultBuf indicate the information returned for each of these levels. 

Regardless of the level specified, a DosFindFirst2 request (and an associated DosFindNext request) 
always includes the information returned by level 1 as part of the information that is returned. 
However, when level 1 information is specifically requested, an inclusive search is made. That is, all 
normal file entries plus all entries matching any specified attributes are returned. 

Reserved (ULONG) - input 

Reserved, must be set to zero. 
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rc ( USHORT) - 

return 

Return code descriptions are: 

0 

NO_ERROR 

2 

ERROR_FILE_NOTJ r OUND 

3 

ERROR_PATH_NOT_FOUND 

6 

ERROR JNVALID_HANDLE 

18 

ERROR_NO_MORE_FILES 

26 

E R R O R_NOT_DOS_D 1 S K 

87 

ERRORJNVALID_PARAMETER 

108 

ERROR_DRIVE_LOCKED 

111 

ERROR_BUFFER_OVERFLOW 

113 

ERROR_NO_MORE_SEARCH_HANDLES 

206 

ERROR_FILENAMEJEXCED_RANGE 

208 

ERROR_META_EXPANSION TOO LONG 

254 

ERRORJNVALIDJEAJMAME 

255 

ERRORJEAJJSTJN CONSISTENT 

275 

ERROR_EAS_DIDNT_FIT 

Remarks 



DosFindFirst2 returns directory entries (up to the number requested in SearchCount) and extended attri- 
bute information for as many files or subdirectories whose names, attributes, and extended attributes 
match the specification, and whose information fits in ResultBuf. On output, SearchCount contains the 
actual number of directory entries returned. 

DosFindNext uses the directory handle associated with DosFindFirst2 to continue the search started by 
the DosFindFirst2 request. 

Any non-zero return code except ERROR_EAS_DIDNT_FIT indicates no handle has been allocated. This 
includes such non-error indicators as ERROR_NO_MORE_FILES. 

For programs running without the NEWFILES bit set, only 8.3 filename format names are returned. These 
names are changed to uppercase. 

In the case of ERRORJEAS_DIDNT_FIT, a search handle is returned, and a subsequent call to DosFindNext 
will get the next matching entry in the directory. You may use DosQPathlnfo to retrieve the EAs for the 
matching entry by using the EA arguments that were used for the DosFindFirst2 call and the name that 
was returned by DosFindFirst2. 

In the case of ERRORJEAS_DIDNT_FIT, only information for the first matching entry is returned. This entry 
is the one whose EAs did not fit in the buffer. The information returned is in the format of that returned for 
InfoLevel 2. No further entries are returned in the buffer even if they could fit in the remaining space. 


Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following 
restrictions apply to DosFindFirst when coding for the DOS mode: 

DirHandle must always equal hex 0001 H or FFFFH on the initial call to DosFindFirst. Subsequent calls to 
DosFindFirst must have a DirHandle of hex 0001 H unless a DosFindClose had been issued. In this case, 
0001 H or FFFFH is allowed. 
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C Language 

typedef struct _FDATE { /* fdate */ 

unsigned day : 5; /* binary day for directory entry */ 

unsigned month : 4; /* binary month for directory entry */ 

unsigned year i 7; /* binary year for directory entry */ 

} FDATE; 

typedef struct JFTIME { /* ftime */ 

unsigned twosecs ; 5; /* binary number of two-second increments */ 

unsigned minutes : 6; /* binary number of minutes ie/ 

unsigned hours : 5; /it binary number of hours if/ 

} FTIME; 

typedef struct JILEFINDBUF { /* findbuf */ 

FDATE fdateCreation; /* file date of creation if/ 

FTIME ftimeCreation; /* file time of creation */ 

FDATE fdateLastAccess; /if file date of last access */ 

FTIME ftimeLastAccess; /* file time of last access */ 

FDATE fdatelastWrite; /* file date of last write */ 

FTIME f time Las tWrite; /* file time of last write */ 

ULONG cbFile; /* file end of data */ 

ULONG cbFileAUoc; /* file allocation *7 

USHORT attrFile; /if file attribute if/ 

UCHAR cchName; /* length of ASCIIZ name string if/ 

CHAR achName[CCHMAXPATHCOMP] ; /* ASCIIZ name string */ 

} FILEFI NDBUF ; 

typedef struct JILEFINDBUF2 { /* findbuf if/ 

FDATE fdateCreation; /* file date of creation */ 

FTIME ftimeCreation; /* file time of creation */ 

FDATE fdateLastAccess; /* file date of last access */ 

FTIME ftimeLastAccess; /* file time of last access */ 

FDATE fdateLastWrite; /if file date of last write */ 

FTIME ftimeLastWrite; /if file time of last write if/ 

ULONG cbFile; /* file end of data if/ 

ULONG cbFileAUoc; /* file allocation */ 

USHORT attrFile; /* file attribute */ 

ULONG cbList; /if level 2 only field (calculate size of buffer) if/ 

UCHAR cchName; /* length of ASCIIZ name string if/ 

CHAR achName [CCHMAXPATHCOMP] ; /if ASCIIZ name string */ 

} FILEFINDBUF2; 
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typedef struct _GEA { /* gea */ 

BYTE cbName; /* name length not Including NULL */ 

CHAR szNametl]; /* attribute name */ 

} GEA; 

typedef struct _GEALIST { /* geal */ 

ULONG cbList; /* total bytes of structure including full list */ 

GEA list [1] ; /* variable length GEA structures */ 

} GEALIST ; 

typedef struct _FEA { /* fea */ 

BYTE fEA; /* flags */ 

BYTE cbName; /* name length not including NULL */ 

USHORT cbValue; /* value length */ 

} FEA; 

typedef struct _FEALIST { /* feal */ 

ULONG cbList; /* total bytes of structure including full list */ 

FEA list [1] ; /* variable length FEA structures */ 

} FEALIST; 

typedef struct _EA0P { /* eaop */ 

PGEALIST fpGEAList; /* general EA list */ 

PFEALIST fpFEAList; /* full EA list */ 

ULONG oError; 

> EAOP; 

#define INCLJOSFILEMGR 

USHORT rc = DosFindFirst2(FileName, DirHandle, Attribute, ResultBuf, 

Result BufLen, SearchCount, Reserved); 


PSZ 

FileName; 

/* File path name */ 

PHDIR 

DirHandle; 

/* Directory search handle */ 

USHORT 

Attribute: 

/* Search attribute */ 

PVOID 

ResultBuf; 

/* Result buffer */ 

USHORT 

ResultBuf Len; 

/* Result buffer length * 

PUSHORT 

SearchCount; 

/* Number of entries to find */ 

USHORT 

FilelnfoLevel ; 

/* File data required */ 

ULONG 

0; 

/* Reserved (must be zero) */ 

USHORT 

rc; 

/* return code */ 
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Assembler Language 

FDATE struc 
fdate_fs dw ? 

FDATE ends 

FT I ME struc 

ftime_fs dw ? 

FT I ME ends 

FILEFINDBUF struc 

findbuf_fdateCreation dw (size FDATE) /2 dup (?) ;file date of creation 

findbuf_ftimeCreation dw (size FTIMEJ/2 dup (?) ;file time of creation 

findbuf_f date Last Access dw (size FDATE) /2 dup (?) ; f i 1 e date of last access 

findbuf_f time Last Access dw (size FTIME)/2 dup (?) ; f i 1 e time of last access 

fi ndbuf _f date Las tWrite dw (size FDATE) /2 dup (?) ;file date of last write 

findbuf_ftimeLastWrite dw (size FTIME)/2 dup (?) ;file time of last write 

fi ndbuf _cbFile dd ? ;f i 1 e end of data 

fi ndbuf _cbFileAlloc dd ? ; f i 1 e allocation 

fi ndbuf _attrFile dw ? ;f i 1 e attribute 

fi ndbuf _cchName db ? ; length of ASCI IZ name string 

findbuf_achName db CCHMAXPATHCOMP dup (?) ;lengtb of ASCI IZ name string 

FILEFINDBUF ends 

FILEFINDBUF2 struc 

findbuf_fdateCreation dw (size FDATE)/2 dup (?) ;f i 1 e date of creation 

findbuf_ftimeCreation dw (size FTIME)/2 dup (?) ;file time of creation 

findbuf_fdateLastAccess dw (size FDATE) /2 dup (?) ;file date of last access 

fi ndbuf _ftimeLast Access dw (size FTlME)/2 dup (?) ;file time of last access 

f i ndbuf_f dateLastWri te dw (size FDATE)/2 dup (?) ;file date of last write 

findbuf_ftiraelastWrite dw (size FTIME)/2 dup (?) ; f i 1 e time of last write 

fi ndbuf _cbFile dd ? ; f i 1 e end of data 

findbuf_cbFileAlloc dd ? ;file allocation 

fi ndbuf _attr File dw ? ; f i 1 e attribute 

fi ndbuf 2_cbLi st dd ? ; level 2 only field (calculate size of buffer) 

findbuf_achName db CCHMAXPATHCOMP dup (?) ;length of ASCI IZ name string 

fi ndbuf _achName db 13 dup (?) ;ASCI IZ name string 

FILEFINDBUF2 ends 
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GEA st rue 

gea_cbName db ? ;name length not including NULL 

gea_szName db 1 dup (?) attribute name 

GEA ends 

GEALIST struc 

geal_cbList dd ? ; total bytes of structure including full list 

gealjist db size GEA * 1 dup (?) variable length GEA structures 

GEALIST ends 

FEA struc 

fea_fEA db ? ;flags 

fea_cbName db ? ;name length not including NULL 
fea_cbValue dw ? ; value length 

FEA ends 

FEALIST struc 

feal_cbList dd ? ; total bytes of structure including full list 

fealjlist db size FEA * 1 dup (?) ;variable length FEA structures 

FEALIST ends 

EAOP struc 

eaop_f pGEALi st dd ? ; general EA list 
eaop_fpFEAList dd ? ;f ul 1 EA list 

eaop_oError dd ? ; 

EAOP ends 

EXTRN DosFindFirst2:FAR 
INCL_DOSFILEMGR EQU 1 

PUSH® ASCI IZ FileName ; Fi 1 e path name string 

PUSH® WORD DirHandle ;Di rectory search handle (returned) 

PUSH WORD Attribute ; Search attribute 

PUSH® OTHER ResultBuf ;Result buffer 

PUSH WORD ResultBufLen ; Result buffer length 

PUSH® WORD SearchCount ; Number of entries to find 
PUSH WORD FilelnfoLevel ;File data required 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosFindFirst2 

Returns WORD 
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This call locates the next set of directory entries that match the name specified in the previous 
DosFindFirst, DosFindFirst2, or DosFindNext call. 


DosFindNext (DlrHandle, ResultBuf, ResultBufLen, SearchCount) 

Parameters 

DlrHandle (HDIR) - input 

Handle associated with a previous DosFindFirst or DosFindNext function call. 

ResultBuf (PFILEFINDB UF) - output 

Address of the directory search information structure. The information reflects the last DosClose or 
DosBuf Reset call. 

It is possible, if the EA information for a file is 64K, that the system can never be able to return the 
full EA information for a file. 

For the continuation of an FilelnfoLevel 3 search, this buffer should contain input in the same format 
as a DosFindFirst2 FilelnfoLevel 3 search. 

Illedate (FDATE) 

Structure containing the date of file creation. 

Bit Description 

15-9 Year, in binary, of file creation 
8-5 Month, in binary, of file creation 

4-0 Day, in binary, of file creation. 

filetime (FTIME) 

Structure containing the time of file creation. 

Bit Description 

15-11 Hours, in binary, of file creation 

10-5 Minutes, in binary, of file creation 

4-0 Seconds, in binary number of two-second increments, of file creation, 

fileaccessdate (FDATE) 

Structure containing the date of last access. See FDATE in filedate. 
fileaccesstime (FTIME) 

Structure containing the time of last access. See FTIME in filetime, 
writeaccessdate (FDATE) 

Structure containing the date of last write. See FDATE in filedate. 
writeaccesstime (FTIME) 

Structure containing the time of last write. See FTIME in filetime. 

fllesize (ULONG) 

File size. 

fllealloc (ULONG) 

Allocated file size. 

fileattrlb (USHORT) 

Attributes of the file, defined in DosSetFileMode. 
length (UCHAR) 

Length of the ASCIIZ name string, 
matchfilename (CHAR) 

ASCIIZ name string for the first occurrence of FileName. 
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DosFindNext - 
Find Next Matching File 


FAPI 


ResultBufLen ( USHORT) - input 
Length of ResultBuf 

SearchCount ( PUSHORT) - input/output 

Address of the number of matching entries requested in ResultBuf. On return, this field contains the 
number of entries placed into ResultBuf. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

18 ERROR_NO_MORE_FILES 

26 ERROR_NOT_DOS_DISK 

87 ERRORJNVALID_PARAMETER 

111 ERROR_BUFFER_OVERFLOW 

275 ERROR_EAS_DIDNT_FIT 

Remarks 

The file name in FileName can contain global file name characters. If no more matching files are found, 
an error code is returned. 

If an ERROR_BUFFER_OVERFLOW error is returned, further calls to DosFindNext will start the search 
from the same entry. 

If an ERROR_EAS_DIDNT_FIT error is returned, then the buffer was too small to hold the EAs for the first 
matching entry being returned. A subsequent call to DosFindNext will get the next matching entry. This 
enables the search to continue if the EAs being returned are too big to fit in the buffer. You may use 
DosQPathlnfo to retrieve the EAs for the matching entry by using the EA arguments that were used for the 
DosFindFirst2 call and the name that was returned by DosFindFirst2. 

In the case of ERROR_EAS_DIDNT_FIT, only information for the first matching entry is returned. This entry 
is the one whose EAs did not fit in the buffer. The information returned is in the format of that returned for 
InfoLevel 2. No further entries are returned in the buffer even if they could fit in the remaining space. 


Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction 
applies to DosFindNext when coding for the DOS mode: 

• DirHandle must always equal 1. 


C Language 

typedef struct _FDATE { /* fdate */ 


unsigned day : 5; 
unsigned month : 4: 
unsigned year : 7; 

} FDATE; 


/* binary day for directory entry */ 
/* binary month for directory entry */ 
/* binary year for directory entry */ 


typedef struct _FTIME { 

unsigned twosecs : 5; 
unsigned minutes : 6; 
unsigned hours ; 5; 

} FTIME; 


/* ftime */ 

/it binary number of two-second increments it/ 
/it binary number of minutes */ 

/it binary number of hours it/ 
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Find Next Matching File 


typedef struct _FI LEFINDBUF { /* findbuf */ 

FDATE fdateCreation; /* file date of creation */ 

FUME ftimeCreation; /* file time of creation */ 

FDATE fdateLast Access; /* file date of last access */ 

FUME ftimeLast Access; /* file time of last access * / 

FDATE fdateLastWrite; /* file date of last write */ 

FTIME ftimeLastWrite; /* file time of last write */ 

ULONG cbFile; /* file end of data */ 

ULONG cbFileAlloc; /* file allocation */ 

USHORT attrFile; /* file attribute */ 

UCHAR cchName; /* length of ASCI I Z name string */ 

CHAR achName[13] ; /* ASCI IZ name string */ 

} FI LEFINDBUF ; 

#define INCLJ50SFILEMGR 

USHORT rc s DosFindNext (DirHandle, ResultBuf, ResultBuflen, SearchCount); 

HDIR DirHandle; /* Directory handle */ 

PFILEFINDBUF ResultBuf; /* Result buffer it/ 

USHORT ResultBufLen; /* Result buffer length */ 

PUSKORT SearchCount; fit Number of entries to find */ 

USHORT rc; /* return code */ 


Assembler Language 

FDATE st rue 
fdate_fs dw ? 

FDATE ends 
FTIME struc 
ftime_fs dw ? 

FTIME ends 
FILEFINDBUF struc 

findbuf_fdateCreation dw (size FDATE) /2 dup (?) ; f i 1 e date of creation 

findbuf_ftimeCreation dw (size FTIME) /2 dup (?) ; f i 1 e time of creation 

findbuf_fdateLastAccess dw (size FDATE) /2 dup (?) ;f i 1 e date of last access 
findbuf_ftimeLastAccess dw (size FTIME) /2 dup (?) ;file time of last access 
findbuf_fdateLastWrite dw (size FDATE)/2 dup (?) ; f i 1 e date of last write 

findbuf_ftimeLastWrite dw (size FTIME)/2 dup (?) ;f i 1 e time of last write 

findbuf_cbFile dd ? ;f i 1 e end of data 

findbuf_cbFileAlloc dd ? ;file allocation 

f i ndbuf_attrFi 1 e dw ? ; f i 1 e attribute 

findbuf_cchName db ? ; length of ASCI I Z name string 

findbuf_achName db 13 dup (?) ;ASCI IZ name string 

FILEFINDBUF ends 

EXTRN DosFindNext: FAR 
INCL_DOSFILEMGR EQU 1 

PUSH WORD DirHandle directory search handle 

PUSH8 OTHER ResultBuf ; Result buffer 

PUSH WORD ResultBuf Len ; Result buffer length 

PUSH@ WORD SearchCount ; Number of entries to find 

CALL DosFindNext 

Returns WORD 
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Find Next Matching File 


FAPI 


Example 

This example gets the 1st file in the current 

Idefine INCL_DOSFILEMGR 

Idefine NORMAL_FILES 0 
Idefine SEARCH PATTERN 
Idefine FILE_ATTRIBUTE NORMAL_FILES 
Idefine RESERVED 0L 

HDIR FindHandle; 

FILEFINDBUF FindBuffer; 

USHORT FindCount; 

USHORT rc; 

FindHandle « 0x0001; 

FindCount - 1; 


if (! DosFi ndFi rst (SEARCH_PATTERN , /* 

&FindHandle, /* 

FILE_ATTRIBUTE, /* 

&FindBuffer, /* 

si zeof (FindBuffer), /* 
SFindCount, /* 

RESERVED)) /* 

rc * DosFindNext (FindHandle, /* 

iFindBuffer, /* 

si zeof (FindBuffer), /* 
fcFindCount) ; /* 


directory, and then gets the next file. 


File pattern */ 

Directory search handle *7 
Search attribute */ 

Result buffer */ 

Result buffer length */ 

I of entries to find */ 
Reserved (must be zero) */ 
Directory handle */ 

Result buffer */ 

Result buffer length */ 

I of entries to find */ 
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Set Process External Event Flag 


This call allows one process to set an external event flag for another. 


DosFlagProcess (ProcessID, ActionCode, Flagnum, Flagarg) 


Parameters 

ProcessID (P/D) - Input 

ID of the process or root process of the process tree, who is to receive notification that the flag event 
has occurred. 

ActionCode (USHORT) - input 

Indicates who is to receive notification that the flag event has occurred. 

Value Definition 

0 The indicated process and all its descendant processes are flagged. (Detached proc- 
esses cannot be flagged.) The indicated process must be the current process or one it 
has created as a non-detached process. If the indicated process terminates, its 
descendants are still flagged. 

1 Only the Indicated process is flagged. Any process can be specified. 

Flagnum ( USHORT) - input 

Number of the flag event whose occurrence is to be signalled as shown below: 

Value Definition 

0 Flag A 

1 Flag B 

2 Flag C. 

Flagarg (USHORT) - input 

An argument passed to indicated processes. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERRORJNVALID_FUNCTION 

156 ERR0R[SIGNAL_REFUSED 

186 ERRORJNVALID_FLAG_NUMBER 

303 ERRORJNVALID_PROCID 

Remarks 

A process issues DosFlagProcess to set one of three user-defined flags available to the process. The 
meaning of the flag is defined by the flag user — the process that receives the signal generated by the 
OS/2 signal mechanism upon the setting of the flag. 

When the flag user is signaled, its reaction to the signal depends on values it has specified with 
DosSetSigHandler. For example, it can respond by giving control to a signal handler it has registered 
with DosSetSigHandler for the signal that corresponds to the user flag (SIGPFA corresponds to Flag A, 
and so on). Or, the flag user can ignore the signal and return an error code to the flagger. 

If no action is specified with DosSetSigHandler by a process for a user flag, the default is to ignore the 
signal. 
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DosFlagProcess - 

Set Process External Event Flag 


C Language 

fdefine INCLJOSSIGNALS 


USH0RT rc ** DosFlagProcess (ProcessID, ActionCode, Flagnum, Flagarg); 


P1D 

USHORT 

USHORT 

USHORT 


ProcessID; 

ActionCode; 

Flagnura; 

Flagarg; 


/* Process ID to flag */ 

/* Indicate to flag descendants */ 
/* Flag number */ 

/* Flag argument */ 


USHORT rc; 


/* return code */ 


Assembler Language 

EXTRN DosFlagProcess; FAR 
INCL_DOS$IGNALS EQU 1 


PUSH 

WORD 

ProcessID 

PUSH 

WORD 

ActionCode 

PUSH 

WORD 

Flagnum 

PUSH 

WORD 

Flagarg 

CALL 

DosFlagProcess 


; Process ID to flag 
indicate to flag descendants 
;Flag number 
;F1ag argument 


Returns WORD 


Example 

This example starts a program named 'simple2.exe', and then signals the program with the external flag 
A. 


#define INCLJJOSPROCESS 
#define INCLJJOSSIGNALS 

#define PROGRAM_NAME "simple2.exe" 

CHAR Load Error [100] ; 

PSZ Args ; 

PSZ Envs; 

RESULTCODES ReturnCodes; 

USHORT FlagArg; 

USHORT rc; 


FlagArg = 2; 


i f ( ! Dos ExecPgm( Load Error, 

/* Object name buffer */ 

sizeof(LoadError), 

/* Length of object name buffer */ 

EXEC_ASYNC, 

/* Asynchronous/Trace flags */ 

Args, 

/* Argument string */ 

Envs, 

/* Environment string */ 

&ReturnCodes, 

/* Termination codes */ 

PR0GRAM_NAME) ) 

/* Program file name */ 

rc = DosFlagProcess (ReturnCodes. codeTerminate, /* Process ID to flag */ 

FLGP PID, 

/* Indicate to flag descendants 

pflgIa. 

/* Flag number */ 

FlagArg) ; 

/* Flag argument */ 


The following example Illustrates the use of a user-defined flag to signal time-critical events. The main 
thread installs a routine, named FlagA_Handler(), as the signal handler for user-defined Flag A. It then 
creates a thread and blocks on a reserved RAM semaphore; this thread obtains its process ID and 
signals the main thread via Flag A. The main thread responds by executing the signal handler. 
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Idefine INCLJ50SPR0CESS 
Idefine INCL_DOS$IGNALS 
#de fine INCLJJOSERRORS 

#incl ude <os2.h> 

#de fine TIMEOUT 5000L 

TID ThreadID; 

BYTE ThreadStack[4000] ; 

VOID APIENTRY FlagA_Handler(argl, arg2) /* Define signal handler */ 

USHORT argl; 

USHORT arg2; 

{ 

printf ("Handler for Flag A now running. \n") ; 
return; 

> 

VOID APIENTRY Thread_A() 

{ 

PIDINFO Pidlnfo; 

USHORT FlagArg; 

USHORT rc; 

DosGetPID(&PidInfo) ; 

printf ("Process ID is %d\n", Pidlnfo. pid) ; 
if(l(rc * DosFlagProcess(PidInfo.pid t 
FLGP_PID, 

PFLG_A, 

FlagArg))) 

printf ("FlagA signal sent from ThreadA to main thread. \n"); 
else 

printf (“FI agProcess rc is %d\n‘\ rc)/* Error processing on rc */; 
DosExit(EXIT_THREAD. /* Action Code */ 

RETURN_CODE) ; /* Result Code */ 


main() 

{ 

ULONG RamSem - OL; 

ULONG far *RamSemHandle = &RamSem; 

USHORT rc; 

if (1 (rc a DosSetSigHandler((PFNSIGHANDLER) FlagA Handler, 

NULL, 

NULL, 

SIGA ACCEPT, 

SIG__PFLG_A))) 

printf ("Main thread has set FlagA handler.\n“); 
else 

/* Error processing on rc */; 
i f ( ! (rc=DosSemRequest ( RamSemHandl e , 

TIMEOUT))) 

pri nt f ( “ Semaphore obtai ned . \n“ ) ; 
i f ( ! (DosCreateThread( (PFNTHREAD) Thread_A, 

&ThreadID, 

&ThreadStack [3999] ) ) ) 
printf (“ThreadA created. \n"); 

printf (“Main thread will now wait on a Ramsem for a while.\n“); 
i f ( (rc=Dos$emRequest (RamSemHandl e , 

TIMEOUT)) 

== ERRORJNTERRUPT) 

printf ("Main thread interrupted while waiting, rc is %d.\n", rc); 

} 
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DosFreeModule - 
Free Dynamic Link Module 


This call frees the reference to a dynamic link module for a process. When the dynamic link module is no 
longer needed by any process, the module is freed from system memory. 


DosFreeModule (ModuleHandle) 


Parameters 

ModuleHandle ( HMODULE ) - Input 

Handle returned by DosLoadModule. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

6 ERRORJNVALID_HANDLE 

12 ERRORJNVALIDACCESS 

95 ERRORJNTERRUPT 

Remarks 

The module identified by the handle must be loaded through DosLoadModule. An error is returned If the 
handle is invalid. 

If any exit list routines were registered as a result of this module being loaded, the module may not be 
freed and ERROR_INVALID_ACCESS may be returned. 

When DosFreeModule returns to the caller, the module handle is no longer valid and is not used to refer- 
ence the dynamic link module. Procedure entry addresses returned for this module are no longer valid 
and cause a protection fault if they are invoked. 

C Language 

#define INCL_DOSMODULEMGR 

USHORT rc = DosFreeModule (ModuleHandle) ; 

HMODULE ModuleHandle; /* Module handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosFreeModule: FAR 
INCL_DOSMODULEMGR EQU 1 

PUSH WORD ModuleHandle ;Module handle 
CALL DosFreeModule 

Returns WORD 
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DosFreeModule - 
Free Dynamic Link Module 


Example 

This example tries to load module ABCD. The system searches LIBPATH. If unsuccessful, the system 
tries to to load the module from the program's directory (in case the user forgot to update LIBPATH). 

Idefine I NCL_DOSMODULEMGR 

Idefine MODULE_NAME ‘'abed 11 

#de fine FULL_MODULE_NAME M \\nifty\\abcd.dll ■ 

CHAR LoadError[100]; 

HMODULE ModuleHandle; 

USHORT rc; 

if (DosLoadModule(LoadError, 

sizeof(LoadError), 

MQDULE_NAME , 

&McduleHandle) == 2) 
rc = DosLoadModule( Load Error, 

sizeof (LoadError) , 

FULLJ40DULEJIAME, 

&ModuleHand7e); 

rc » DosFreeModule(McduleHandle); 


/* Object name buffer */ 

/* Length of object name buffer */ 
/* Module name string */ 

/* Module handle */ 

/* Object name buffer */ 

/* Length of object name buffer */ 
/* Module name string */ 

/* Module handle */ 

/* Module handle */ 
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Free Resource 


This call frees a resource loaded by DosGetResource2. 


DosFreeResource (ResAddr) 


Parameters 

ResAddr (PBYTE) - input 

The address of the resource to free. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

6 ERROR_ACCESS_DENIED 

Remarks 

DosFreeResource is used to free resources obtained with DosGetResource2. 

After the last reference to a resource is freed, the memory becomes available for reuse by the system. 
However, the memory is not reused until the system determines it cannot satisfy a memory allocation 
request. This allows the resource to remain in memory in case the process issues another 
DosGetResource2 call. The system thus avoids having to reread the contents of the resource from disk. 

C Language 

^define INCLJ50SFREERESOURCE 
USHORT rc = DosFreeResource (ResAddr) ; 

PBYTE ResAddr; /* Resource address */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosFreeResource : FAR 
INCL_DOSFREERESOURCE EQU 1 

PUSH DWORD ResAddr ; Resource address 

CALL DosFreeResource 

Returns WORD 
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DosFreeSeg - 
Free Segment 


This call deallocates a memory segment. 


DosFreeSeg (Selector) 


Parameters 

Selector (SEL) - input 

Selector of the segment to be freed. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

212 ERROR_LOCKED 

Remarks 

DosFreeSeg frees selectors to segments returned by allocation calls to DosAllocSeg, DosAllocShrSeg, 
and DosAMocHuge. In addition, DosFreeSeg frees a selector returned by a call to DosCreateCS Alias. If a 
CS alias selector has been created for a data segment by a call to DosCreateCSAIias, the CS alias 
selector Is still valid after the segment’s data selector has been freed. 

When allocated memory is shared, all selectors to the shared memory must be freed before the memory 
is deallocated. For example, if memory allocated by DosAllocSeg or DosAMocHuge has been given to 
another process with DosGiveSeg, the giver usually frees its selector by a call to DosFreeSeg. The recip- 
ient, in turn, frees the selector passed to it, after it has accessed the shared memory with DosGetSeg. 

DosFreeSeg decrements the reference count for named shared segments allocated by DosAllocShrSeg. 
Access to the segment with DosGetShrSeg increments this count. When the count is 0, the memory is 
deallocated. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction 
applies to DosFreeSeg when coding for the DOS mode: 

If DosFreeSeg is issued on a CSAHased segment it deallocates the associated memory. This is incon- 
sistent with the OS/2 mode, because DosFreeSeg must be performed on both the original and CSAIiased 
selectors. 

C Language 

Idefine INCL_DO$MEMMGR 

USHORT rc ■ DosFreeSeg(Selector); 

SEL Selector; /* Selector */ 

USHORT rc; /* return code */ 
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Free Segment 


FAPI 


Assembler Language 

EXTRN DosFreeSeg: FAR 
INCL_DOSMEMGR EQU 1 

PUSH WORD Selector Selector 
CALL DosFreeSeg 

Returns WORD 

Example 

This example allocates a segment of 30,250 bytes and then discards the segment. 

Idefine INCLJJOSMEMGR 

Idefine NUMBER_OF_BYTES 30250 
Idefine ALL0C_FLAG SEG_GETTABLE 

SEL Selector; 

USHORT rc; 

rc = Dos A1 locSeg( NUMBER _0F_8YTES, 

SSelector, 

ALLOC_FLAG) ; 

rc = DosFreeSeg (Selector); 


/* # of bytes requested */ 
/* Selector allocated */ 
/* Allocation flags */ 

/* Segment selector */ 
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DosFSAttach - 

Creates and Destroys FSD Connections 


DosFSAttach attaches or detaches drive to/from a remote FSD, or a pseudo-character device name 
to/from a local or remote FSD. 


DosFSAttach (DeviceName, FSDName, Data Buffer, DataBufferLen, OpFlag, Reserved) 


Parameters 

DevIceName (PSZ) - input 

Points to either the drive letter followed by a coion, or points to a pseudo-character device name. If 
DeviceName is a drive, it is an ASCIIZ string having the form of drive letter followed by a colon. If an 
attach is successful, all requests to that drive are routed to the specified FSD. If a detach is suc- 
cessful, the drive disappears from the system’s name space. 

If DeviceName is a pseudo-character device name (single file device), its format is that of an ASCIIZ 
string in the format of an OS/2 filename in a subdirectory called \DEV\. All requests to that name are 
routed to the specified FSD after a successful attach. A successful detach removes the name from 
the system’s name space. 

FSDName (PSZ) - input 

Address of the ASCIIZ name of the remote FSD to attach to or detach from DeviceName. 

DataBuffer (PBYTE) — input 

Points to the user-supplied FSD argument data area. The meaning of the data is specific to the FSD. 
The DataBuffer contains contiguous ASCIIZ strings, with the first word of the buffer containing the 
number of ASCIIZ strings. 

DataBufferLen (USHORT) - input 
The byte length of the data buffer. 

OpFlag (USHORT) - input 

Defines the type of operation to be performed. Attach = 0 and Detach = 1. 

Reserved (ULONG) - input 

Reserved, must be set to zero. 

rc (USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOT_ENOUGH_M EMORY 

15 ERROR JNVALID_DRIVE 

124 ERROR JNVALID_LEVEL 

252 ERRORJNVALID_FSD_NAME 

253 ERRORJNVALID_PATH 

Remarks 

The redirection of drive letters representing local drives is not supported. 

FSDs that wish to establish open connections that are not attached to a name in the system’s name 
space, for such purposes as optimizing UNC connections or establishing access rights, must use an 
DosFSCtl function to do so. DosFSAttach only creates attachments to drives or devices in the system’s 
name space. 

See description of pseudo-character devices. 
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DosFSAttach - 

Creates and Destroys FSD Connections 


C Language 

#define INCLJJOSFILEMGR 

USHORT rc = DosFSAttach ( Devi ceName, FSDName, DataBuffer, DataBufferLen, OpFlag, 0); 

PSZ Devi ceName; /* Device name or drive letter string */ 

PSZ FSDName; fie FSD name */ 

PBYTE DataBuffer; /* Attach argument data ief 

USHORT DataBufferLen; fie Buffer length ief 

USHORT OpFlag; /ie Attach or detach ief 

ULONG 0; fie Reserved (must be zero) ief 

USHORT rc; /ie return code ief 


Assembler Language 

EXTRN DosFSAttach; FAR 
INCL_DOSFILEMGR EQU 1 

PUSH0 ASCI I Z DeviceName ;Device name or drive letter string 

PUSH? ASCI I Z FSDName ;FSD name 

PUSH0 OTHER DataBuffer ;Attach argument data 

PUSH WORD DataBufferLen ;Buffer length 

PUSH WORD OpFlag ; Attach or detach 

PUSH DWORD 0 Reserved (must be zero) 

CALL DosFSAttach 

Returns WORD 
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DosFSCtl - 

Provide File System Control 


DosFSCtl provides an extended standard Interface between an application and an FSD. 


DosFSCtl (DataArea, DataLengthMax, DataLength, ParmList, ParmLengthMax, ParmLength, 
FunctionCode, RouteName, FileHandle, RouteMethod, Reserved) 


Parameters 

DataArea (PBYTE) - input 
Address of the data area. 

DataLengthMax ( USHORT) - input 

The maximum length in bytes to be returned by the FSD in DataArea. DataLength may be longer 
than this on input, but not on output. 

DataLength (PUSHORT) - input/output 

Address of the length in bytes of data in DataArea. On input, it is the length of data being sent, and 
on output is the length of the data that was returned by the FSD. If ERROR_BUFFER_OVERFLOW is 
returned from the call, then it is the size of the buffer required to hold the data returned by the FSD. 

ParmList (PBYTE) - input 

Address of the command specific parameter list. 

ParmLengthMax ( USHORT) - input 

The maximum length in bytes of the data to be returned by the FSD in ParmList. ParmLength may be 
longer than this on Input, but not on output. 

ParmLength ( PUSHORT) - input/output 

Address of, on input, the length in bytes of parameters passed in by the application, and on return it 
is the length of parameters returned by the FSD. If ERROR_BUFFER_OVERFLOW is returned from the 
call, then it is the size of the buffer required to hold the parameters returned by the FSD. No other 
data is returned in this case. 

FunctionCode ( USHORT) - input 

The file system-specific function code. For remote FSDs, there are two kinds of possible FsCtl calls: 
FsCtl calls that are handled locally, and FsCtl calls that are exported across the network. If bit 
0x4000 is set in the function code, then this indicates to the remote FSD that the function should be 
exported. The range of function codes are split up as follows: Function codes between 0x0000 and 
0x7FFF are reserved for use by OS/2. Function codes between 0x8000 and OxBFFF are FSD defined 
FsCtl functions handled by the local FSD. Function codes between OxCOOO and OxFFFF are FSD 
defined FsCtl functions exported to the server. 

FunctionCode = 1: returns FSD error code Information. Error code is passed to the FSD in the first 
word of ParmList. On return, the first word of the Data area contains the length of the following 
ASCIIZ string. The ASCIIZ string begins at the second word and is an explanation of the error code. 

RouteName ( PSZ ) - input 

Address of the ASCIIZ name of the FSD, or the pathname of a file or directory the operation should 
apply to. 

FileHandle (HFILE) - input 

The file or device specific handle. 

RouteMethod ( USHORT) - input 

Selects how the request is routed. 

Value Definition 

1 FileHandle directs routing. RouteName must be a NUL pointer (0L). The FSD associated 

with the handle receives the request. 
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Provide File System Control 


2 RouteMethod refers to a pathname, that directs routing. FileHandle must be —1. The 
FSD associated with the drive that the pathname refers to at the time of the request 
receives the request. The pathname need not refer to a file or directory that actually 
exists, only to a drive. A relative pathname may be used, it is processed like any other 
pathname. 

3 RouteMethod refers to an FSD name, that directs routing. FileHandle must be —1. The 
named FSD receives the request. 

Reserved ( ULONG ) - input 

Reserved, must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

1 ERRORJNVALID_FUNCTION 

6 ERROR JNVALID^H AN DLE 

87 ERRORJNVALID_PARAMETER 

95 ERRORJNTERRUPT 

111 ERROR_BUFFER_OVERFLOW 

117 ERROR_INVALID_CATEGORY 

124 ERRORJNVALIDJ-EVEL 

252 ERRORJNVALID>SD_NAME 


C Language 

# define 1NCL_D0SFILEMGR 

USHORT rc a DosFSCtl (DataArea, DataLengthMax, DataLength, ParmList, 
ParmLengthMax, ParmLength, FunctionCode, RouteName, 
FileHandle, RouteMethod, 0); 


PBYTE 

DataArea; 

/* Data area */ 

USHORT 

DataLengthMax ; /* Data area length */ 

PUSHORT 

DataLength; 

/* Data area length (returned) */ 

PBYTE 

ParmList; 

/* Parameter list */ 

USHORT 

ParmLengthMax ; /* Parameter list length */ 

PUSHORT 

ParmLength; 

/* Parameter list length (returned) 

USHORT 

FunctionCode 

/* Function code */ 

PSZ 

RouteNarne; 

/* Path or FSD name *7 

HFILE 

FileHandle; 

/* File handle */ 

USHORT 

RouteMethod; 

/* Method for routing. */ 

ULONG 

0; 

/* Reserved (must be zero) */ 

USHORT 

rc; 

/* return code */ 

Assembler Language 

EXTRN DosFSCtl: FAR 


INCl_DOSFILEMGR EQU 1 


PUSH® OTHER 

DataArea 

;Data area 

PUSH WORD 

DataLengthMax 

;Data area length 

PUSH® WORD 

DataLength 

;Data area length (returned) 

PUSH® OTHER 

ParmLi st 

; Parameter list 

PUSH WORD 

ParmLengthMax 

; Parameter list length 

PUSH® WORD 

ParmLength 

; Parameter list length (returned) 

PUSH WORD 

FunctionCode 

; Function code 

PUSH? ASCI IZ RouteNarne 

;Path or FSD name string 

PUSH WORD 

FileHandle 

;File handle 

PUSH WORD 

RouteMethod 

;Method for routing. 

PUSH DW0R0 

0 

Reserved (must be zero) 

CALL DosFSCtl 


Returns WORD 
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DosFSRamSemClear - 
Release a Fast-Safe RAM Semaphore 


This call releases ownership of a Fast-Safe (FS) RAM semaphore. 


DosFSRamSemClear (FSRamSemStructure) 


Parameters 

FSRamSemStructure ( PDOSFSRSEM ) - input 

Address of the FS RAM Semaphore data structure. The content/format of this structure is shown in 
"DosFSRamSem Request - Request Safe RAM Semaphore” on page 2-117. 

rc ( USHORT) - return 

Return code description is: 

0 NO_ERROR 

Remarks 

DosFSRamSemClear decrements fsJJseCount, which is incremented by DosFSRamSemRequest. Recur- 
sive requests for FS RAM semaphores are supported by this use count, which keeps track of the number 
of times the owner has issued a DosFSRamSemRequest without a corresponding DosFSRamSemClear. If 
the call to DosFSRamSemClear decrements the use count to zero, the semaphore is set unowned, and 
any threads that were blocked waiting for the semaphore resume execution. 

DosFSRamSemClear cannot be issued against a FS RAM semaphore that is owned by another thread. 

C Language 

typedef struct _B0SFSR$EM 

USHORT cb; 

PID pid; 

TID tid; 

USHORT cUsage; 

USHORT client; 

ULONG sem; 

} DOSFSRSEM; 

Idefine INCL_DOSSEMAPHORES 

USHORT rc = DosFSRamSemCl ear (FSRamSemStructure); 

PDOSFSRSEM FSRamSemStructure; /* Address of structure */ 

USHORT rc; /* return code */ 


{ /* dosfsrs */ 

/* Length of this structure (bytes) */ 
/* Process ID of owner or zero */ 

/* Thread ID of owner or zero */ 

/* Reference count */ 

/* 16 bit field for use by owner */ 

/* OS/2 Ram Semaphore */ 
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DosFSRamSemClear - 

Release a Fast-Safe RAM Semaphore 


Assembler Language 

DOSFSRSEM struc 

dosfsrs_cb dw ? ; length of this structure (bytes) 
dosfsrsj>id dw ? ; Process ID of owner or zero 

dosfsr$_tid dw ? ; Thread ID of owner or zero 

dosfsrs_cUsage dw ? reference count 

dosfsrs_c1ient dw ? ; 16 bit field for use by owner 
dosfsrs_sem dd ? ;0S/2 Ram Semaphore 

DOSFSRSEM ends 

EXTRN DosFSRamSemCl ear : FAR 
INCL_D0SSEMAPH0RES EQU 1 

PUSH© OTHER FSRamSemStructure ;FS Ram Semaphore data structure 
CALL DosFSRamSemCl ear 

Returns WORD 


Example 

This example requests a FS RAM semaphore and then clears it 

Idefine INCLJ)OSSEMAPHORES 

#define NOT_OWNED 0 
Idefine START 0 
^define START_LONG OL 
#define TIME.OUT 10OOL 

DOSFSRSEM SemStruct; 

USHORT rc; 

SemStruct. cb « si zeof (SemStruct); /* Initialize FS Sem */ 
SemStruct.pid = N0T_0WNED; 

SemStruct. tid = N0T_0WNED; 

SemStruct. cllsage a START; 

SemStruct. client = START; 

SemStruct.sem = START_L0NG; 

i f (IDosFSRamSemRequest (&SemStruct , /* Address of structure */ 

TIME_0UT)) /* Timeout */ 

rc = DosFSRamSemCl ear (iSemStruct); /* Address of structure */ 
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DosFSRamSemRequest - 
Request Safe RAM Semaphore 


This call obtains a Fast-Safe (FS) RAM semaphore and records the current owner for potential cleanup by 
a DosExitList routine. 


DosFSRamSemRequest (FSRamSemStructure, Timeout) 


Parameters 

FSRamSemStructure (PDOSFSRSEM) - input 

Address of the FS RAM Semaphore data structure. The content of this structure is: 

fs_Length ( USHORT) 

Length in bytes of the FSRamSemStructure; 14 is the only valid value. 
fs_ProclD (PID) 

Owning process ID; 0 means the semaphore is not owned. 

fs.ThrdlD (7/D) 

Owning thread ID; 0 means the semaphore is not owned. 
fs_UseCount (USHORT) 

Use count. The number of times the owning thread has issued DosFSRamSemRequest without 
issuing a corresponding DosFSRamSemClear. 

fsClient (USHORT) 

Is a 16-bit pattern used by the owner of a semaphore to record maintenance information about 
the resource managed by the semaphore. 

fs_RAMSem (ULONG) 

The RAM semaphore data structure used in this request. 

Before the initial call to DosFSRamSemRequest, this entire structure must be initialized to zero and 
its length set to 14. Other than fs_Client, the caller should not modify any fields in this structure. 

Timeout (LONG) - input 

The number of milliseconds to wait for the semaphore to be cleared before resuming execution. The 
meaning of the specified values are: 

Value Definition 

— 1 The requestor waits indefinitely when the semaphore is owned. There is no time out. 

0 There is an immediate return if the semaphore is owned. 

>0 The value is the number of milliseconds to wait, if the semaphore is owned. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

121 ERROR_SEM_TIMEOUT 

Remarks 

When DosFSRamSemRequest is called, it checks the status of the semaphore. If it is unowned, then 
DosFSRamSemRequest sets it owned, increments fs_UseCount, and returns immediately to the caller. 

If the semaphore is owned, the caller has the option to block until the semaphore is no longer owned. 

The unblocking of a DosFSRamSemRequest is "level triggered" because it does not actually return 
unless the semaphore remains clear until the affected thread can be redispatched to claim it success- 
fully. The Timeout parameter can be used to place an upper bound on the amount of time to block before 
returning, even though the semaphore remains owned. 

When the thread is done with the protected resource, it calls DosFSRamSemClear. DosFSRamSemClear 
decrements fsJJseCount. Recursive requests for FS RAM semaphores are supported by the use count, 
which keeps track of the number of times the owner has issued a DosFSRamSemRequest without a corre- 
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DosFSRamSemRequest - 
Request Safe RAM Semaphore 


sponding DosFSRamSemClear. If the call to DosFSRamSemClear decrements the use count to zero, the 
semaphore is set unowned, and any threads that were blocked waiting for the semaphore resume exe- 
cution. 

The 16-bit field fs_Client is not interpreted by the FS RAM semaphore calls. Instead, it provides the caller 
with a means of identifying the resource being accessed by the owner of the semaphore. This field is 
initialized to zero when a FS RAM semaphore is first acquired. The owner may place values into this 
field that describe the resource. These values can be used by an exit list handler to determine the appro- 
priate cleanup action. 

When a process terminates while owning a FS RAM semaphore, any routines in the exit list maintained 
by DosExitList are given control. These routines take appropriate steps to guarantee the integrity of 
resources owned by the process. To clean up a resource protected by a FS RAM semaphore, 
DosFSRamSemRequest is called to gain ownership of the semaphore. When issued during exit list proc- 
essing, DosFSRamSemRequest examines the semaphore to determine if the semaphore is owned by the 
active process. It then forces the owning thread ID to be equal to the current thread ID and sets fs_Count 
= 1. This allows the exit list routine to be programmed without any FS RAM semaphore handling 
instructions. When the exit list routine has completed its operations, it restores the resource for use by 
others by issuing DosFSRamSemClear. 

C Language 

typedef struct J50SFSRSEM 

USHORT cb; 

PID pid; 

TID tid; 

USHORT cUsage; 

USHORT client; 

ULONG sem; 

} DOSFSRSEM; 

#define INCLJ30SSEMAPH0RES 

USHORT rc = DosFSRamSemRequest (FSRamSemStructure, Timeout); 

PDOSFSRSEM FSRamSemStructure; /* Address of structure */ 

LONG Timeout; /* Timeout (in milliseconds) */ 

USHORT rc; /* return code */ 


Assembler Language 


DOSFSRSEM struc 




dosfsrs_cb 

dw 

? 

; length of this structure (bytes) 

dosfsrsjiid 

dw 

? 

•.Process ID of owner or zero 

dosf srs_ti d 

dw 

? 

;Thread ID of owner or zero 

dosfsrs_cUsage 

dw 

? 

reference count 

dosfsrs_client 

dw 

? 

;16 bit field for use by owner 

dosfsrs_sem 

dd 

? 

;0S/2 Ram Semaphore 


DOSFSRSEM ends 


EXTRN DosFSRamSemRequest: FAR 
INCLJ30SSEMAPH0RES EQU 1 

PUSHO OTHER FSRamSemStructure ;FS Ram Semaphore data structure 

PUSH DWORD Timeout ; Timeout (in milliseconds) 

CALL DosFSRamSemRequest 

Returns WORD 


{ /* dosfsrs */ 

/* Length of this structure (bytes) */ 
/* Process ID of owner or zero */ 

/* Thread ID of owner or zero */ 

/* Reference count */ 

/* 16 bit field for use by owner */ 

/* OS/2 Ram Semaphore */ 
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DosFSRamSemRequest - 
Request Safe RAM Semaphore 


Example 

This example requests a FS RAM semaphore, 

fdefine INCL_DOSSEMAPHORES 

^define NOT OWNED 0 
#define START 0 
#define START_LONG OL 
#define TIME_0UT 1000L 

DOSFSRSEM SemStruct; 

USHORT rc; 

SemStruct. cb » sizeof (SemStruct) ; /* Initialize FS Sem */ 

SemStruct. pi d = N0T_0WNED; 

SemStruct.tid = N0T_0WNED; 

SemStruct. cUsage = START; 

SemStruct. client = START; 

SemStruct. sem = START_LONG; 

rc = DosFSRamSemRequest (&SemStruct, /* Address of structure */ 

TIME_0UT) ; /* Timeout */ 


Chapter 2. Control Program Function Calls 2-119 



DosGetCollate - 
Get Collate Table 


FAPI 


This call obtains a collating sequence table (for characters hex 00H through FFH) that resides in the 
country information file. It is used by the SORT utility to sort text according to the collating sequence. 


DosGetCollate (Length, Country, MemoryBuffer, DataLength) 


Parameters 

Length ( USHORT) - input 

Length, in bytes, of the data area (MemoryBuffer). A length value of 256 is sufficient 

Country (PCOUNTRYCODE) - input 

Address of the country information structure: 

country ( USHORT) 

Country code identifier. 0 is the default country code, 
codepage ( USHORT) 

Code page identifier. 0 is the code page of the current process. 

MemoryBuffer (PCHAR) - output 

Address of the collating table. This memory area is provided by the caller. The size of the area is 
provided by the input parameter Length. If it is too small to hold all the available information then as 
much information as possible is provided in the available space (in the order that the data would 
appear). If the amount of returned data does not fill the memory area provided by the caller, the 
unaltered memory is set at 0. The buffer format for the returned information is: 

Byte Description 

0 Sort weight of ASCII (0) 

1 Sort weight of ASCII (1) 


255 Sort weight of ASCII (255) 

DataLength (PUSHORT) — output 

Address of the length, in bytes, of the collate table. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

396 ERROR_NLS_NO_COUNTRY_FILE 

397 ERROR_NLS_OPEN_FAILED‘ 

398 ERROR_NO_COUNTRY_OR_CODEPAGE 

399 ERROR_NLS_TABLE_TRUNCATED 

Remarks 

The returned country-dependent information can be for the default country and current process code 
page or for a specific country and code page. For more information see “DosSetCp — Set Code Page" 
on page 2-320. 
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FAPI 


DosGetCollate - 
Get Collate Table 


C Language 

typedef struct ^COUNTRYCODE { /* ctryc */ 

USHORT country; /* country code */ 

USHORT codepage; /* code page */ 

} COUNTRYCODE; 

Idefine INCLDOSNLS 

USHORT rc = DosGetCollate(Length, Structure, MemoryBuffer, OataLength); 

USHORT Length; /* Length of data area provided */ 

PCOUNTRYCODE Structure; /* Input data structure */ 

PCHAR MemoryBuffer; /* Collate table (returned) */ 

PUSHORT DataLength; /* Length of collate table (returned) */ 

USHORT rc; /* return code *7 


Assembler Language 

COUNTRYCODE struc 

ctryc_country dw ? ; country code 
ctryc_codepage dw ? ;code page 

COUNTRYCODE ends 

EXTRN DosGetCollate; FAR 
INCL_DQSNLS EQU 1 

PUSH WORD Length ; Length of data area provided 

PUSH® OTHER Structure ; Input data structure 

PUSH® OTHER MemoryBuffer ; Col late table (returned) 

PUSH® WORD DataLength ; Length of collate table (returned) 

CALL DosGetCol 1 ate 

Returns WORD 

Example 

This example gets a collating sequence table for codepage 850 and the current country, 

♦define INCL_DOSNLS 

♦define CURRENT COUNTRY 0 
♦define NLS_CODEPAGE 850 

COUNTRYCODE Country; 

CHAR CollBuffer[256] ; 

USHORT Length; 

USHORT rc; 

Country. country = CURRENT_COUNTRY ; 

Country. codepage = NLS_CODEPAGE; 

rc = DosGetCol late(sizeof (Coll Buffer), fie Length of data area provided */ 

&Country, fit Input data structure ief 

Coll Buffer, fie Data area to contain collate table */ 

&Length); /* Length of table */ 
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DosGetCp - 

Get Process Code Page 


FAPI 


This call allows a process to query the current process code page and the prepared system code pages. 


DosGetCp (Length, CodePageList, Data Length) 


Parameters 

Length ( USHORT) - input 

Length, in bytes, of CodePageList. This length should be at least 2 bytes. If the length is less than 
the bytes needed to return all the prepared system code pages than the returned CodePageList is 
truncated. 

CodePageList ( PUSHORT) — output 

Address of the list of available system code pages. The format of the information returned in this list 
is: 

Word Description 

1 Current code page identifier 

2 The first prepared code page 

3 The second prepared code page 

N Other prepared system code pages. 

DataLength ( PUSHORT) - output 

Address of the length, in bytes, of the returned data. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

473 ERROR_CPLIST_TOO_SMALL 

Remarks 

If the process code page identifier was previously set by DosSetCp or inherited by a process, it is 
returned to the caller. 

An input list size (length) of two bytes returns only the current process code page identifier. If 
CodePageList length is too small to hold all the available information, then as much information as pos- 
sible is provided in the available space and ERROR_CPLISTTOO_SMALL is returned. 

If no codepages were prepared with the CODEPAGE command, a length of two and current codepage 
identifier value of zero is returned. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction 
applies to DosGetCp when coding for the DOS mode: 

The current process code page, and no more than one prepared system code page, is returned. 

C Language 

Idefine INCL_DOSNLS 


USHORT rc = DosGetCp(Length, CodePageList, DataLength); 


USHORT 

Length; 

/* Length of list */ 

PUSHORT 

CodePageList; 

/* List (returned) */ 

PUSHORT 

DataLength; 

/* Length of list (returned) */ 

USHORT 

rc; 

/* return code */ 
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fapi DosGetCp - 

Get Process Code Page 


Assembler Language 

EXTRN DosGetCp: FAR 

INCLJQSNLS EQU 1 

PUSH WORD Length ; Length of list 

PUSH® WORD CodePageList ;List (returned) 

PUSH® WORD DataLength ; Length of list (returned) 

CALL DosGetCp 

Returns WORD 


Example 

This example gets the current code page and then up to 3 other prepared codepages. 

#def i ne INCLJIOSNLS 

USHORT CpList[8] ; 

USHORT CpSize; 

USHORT rc; 

rc » DosGetCp (si zeof (CpList) , /* Length of list */ 

CpList, /* List */ 

&CpSize); /* Length of returned list */ 
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DosGetCtrylnfo - 
Get Country Information 


FAPI 


This call obtains country-dependent formatting Information that resides in the country information file. 


DosGetCtrylnfo (Length, Country, MemoryBuffer, DataLength) 


Parameters 

Length (USHORT) - input 

Length, in bytes, of the data area (MemoryBuffer). This length should be at least 38 bytes. 

Country {PCOUNTRYCODE) - input 

Address of the country information structure: 

country ( USHORT) 

Country code identifier; 0 is the default country code, 
codepage (USHORT) 

Code page identifier; 0 is the code page of the current process. 

MemoryBuffer ( PCOUNTRYINFO ) - output 

Address of the buffer where the country-dependent data is returned. The application must request 
enough space in memory, a minimum of 38 bytes, to hold the returned data. If the requested space 
is not large enough, the system fills the allocated space with as much data as it can hold. If the 
requested space is too large, the extra memory requested is set to 0. The data is returned in the 
buffer in the following format: 

country (USHORT) 

Country code identifier. 

codepage (USHORT) 

Code page identifier. 

dateformat (USHORT) 

Date format. 

Value Definition 

0 mm/dd/yy 

1 dd/mm/yy 

2 yy/mm/dd 

currency (CHAR) 

Currency identifier, terminated with a null, 
thousandsep (CHAR) 

Thousands separator, terminated with a null, 
decimalsep (CHAR) 

Decimal separator, terminated with a null, 
datesep (CHAR) 

Date separator, terminated with a null, 
tfmesep (CHAR) 

Time separator, terminated with a null. 
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DosGetCtrylnfo - 
Get Country Information 


currencyformat ( UCHAR ) 

The currency bit fields in the following format: 

Bit Description 

7-3 Reserved 

2 0 = Bits 0 and 1 are used. 

1 = Bits 0 and 1 are ignored; the currency indicator replaces the decimal indicator, 
t 0 = No space between the currency indicator and money value. 

1 = One space between the currency indicator and money value. 

0 0 = Currency indicator precedes the money value. 

1 = Currency indicator follows the money value, 

declmalspace (UCHAR) 

Number (in binary) of decimal spaces used to indicate currency value, 
tfmeformat (UCHAR) 

Time format for presentation in file directory: 

Bit Description 

7-1 Reserved 

0 0 = 12-hour format 

1 = 24-hour format. 

reserved ( USHORT) 

Reserved, set to zero. 

datallstsep (CHAR) 

Data list separator, terminated with a null. 

reserved (USHORT) 

Reserved, set to zero. 

DataLength (PUSHORT) - output 

Address of the length, in bytes, of the country dependent information. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

396 ERROR_NLS_NO_COUNTRY_FILE 

397 ERROR_NLS_OPEN_FAILED 

398 ERROR_NO_COUNTRY_OR_CODEPAGE 

399 ERROR_NLS_TABLE_TRUNCATED 

Remarks 

The returned country dependent information may be for the default country and current process code 
page, or for a specific country and code page. For more information on code page, see "DosSetCp - 
Set Code Page” on page 2-320. 

Family API Considerations 

Some options operate differently in DOS mode than in OS/2 mode. Note that not all country information Is 
available in DOS 3.3. 
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DosGetCtrylnfo - 

Get Country Information 


FAPI 


C Language 

typedef struct _C0UNTRYC0DE { /* 

USHORT country; /* 

USHORT codepage; /* 

} COUNTRYCODE; 

typedef struct .COUNTRY INFO { /* 

USHORT country; 

USHORT codepage; 

USHORT fsDateFmt; 

CHAR s2Currency[5]; 

CHAR szThousandsSeparator[2] ; 
CHAR szDeci mal [2] ; 

CHAR szDateSeparator[2]; 

CHAR szT i meSeparator [2] ; 

UCHAR fsCurrencyFmt; 

UCHAR cDeci mal PI ace ; 

UCHAR fsTimeFmt; 

USHORT abReservedl[2] ; 

CHAR szDataSeparator [2] ; 

USHORT abReserved2[5] ; 

} COUNTRY INFO; 

Idefine INCL.OOSNLS 

USHORT rc = DosGetCtrylnfo (Length, 


USHORT Length; /* 
PCOUNTRYCODE Structure; /* 
PCOUNTRYINFO Memory Buffer; /* 
PUSHORT DataLength; /* 

USHORT rc; /* 


ctryc */ 

country code */ 
code page */ 


ctryi */ 

/* country code */ 
lie code page */ 

/ie date format ie/ 
fie currency indicator ie/ 

/ie thousands separator ie/ 

/ie decimal separator * / 

/ie date separator ie/ 

/ie time separator ie/ 

/ie bit fields for currency format ie/ 
/ie currency decimal places ie/ 

/ie Time format (AM/PM or 24 hr) ie/ 
/ie reserved (0) ie/ 

/ie Data list separator ie/ 

/ie reserved (0) ie/ 


Structure, MemoryBuffer, DataLength); 

Length of data area provided */ 

Input data structure */ 

Country information (returned) ie/ 
Length of data (returned) ie/ 

return code ie/ 
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DosGetCtrylnfo - 
Get Country Information 


Assembler Language 

COUNTRYCODE struc 

ctrycjrountry dw ? ; country code 
ctryc_codepage dw ? ;code page 

COUNTRYCODE ends 

COUNTRYINFO struc 

ctryi_country dw ? ; country code 

ctryi_codepage dw ? ;code page 

ctryi_fsDateFmt dw ? ;date format 

ctryi_szCurrency db 5 dup (?) currency indicator 

ctryi_szThousands$eparator db 2 dup (?) thousands separator 
ctryi_szOecimal db 2 dup (?) ;decimal separator 

ctryi_szDateSeparator db 2 dup (?) ;date separator 

ctryi_szTimeSeparator db 2 dup (?) ;time separator 

ctryi_fsCurrencyFmt db ? ;bit fields for currency format 

ctryi_cDecimalPlace db ? ; currency decimal places 

ctryi_fsTimeFmt db ? ;Time format (AM/PM or 24 hr) 

ctryi_abReservedl dw 2 dup (?) reserved (0) 

ctryi_szDataSeparator db 2 dup (?) ;Data list separator 

ctryi_abReserved2 dw 5 dup (?) ; reserved (0) 

COUNTRYINFO ends 

EXTRN DosGetCtrylnfo: FAR 
INCL_DOSNLS EQU 1 

PUSH WORD Length ; Length of data area provided 

PUSH® OTHER Structure ; Input data structure 

PUSH® OTHER MemoryBuffer ; Country information (returned) 

PUSH® WORD DataLength ; Length of data (returned) 

CALL DosGetCtrylnfo 

Returns WORD 

Example 

This example gets country-dependent information. 

Idefine INCL_DOSNLS 

Idefine CURRENT_COUNTRY 0 
Idefine NLS_CODEPAGE 850 

COUNTRYCODE Country; 

COUNTRYINFO CtryBuffer; 

USHORT Length; 

USHORT rc; 

Country. country = CURRENT_COUNTRY ; 

Country. codepage = NLS_CODEPAGE; 

rc » DosGetCtry Inf o(sizeof (CtryBuffer), /* Length of data area provided */ 

aCountry, /* Input data structure */ 

SCtryBuffer, /* Data area to be filled by function */ 

aLength); /* Length of data returned */ 
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DosGetDateTime - 
Get Current Date and Time 


FAPI 


This call gets the current date and time maintained by the operating system. 


DosGetDateTime (DateTfme) 


Parameters 

DateTime ( PDATETIME ) - output 

Address of the date and time structure: 

hours (UCHAR) 

Current hour. 

minutes (UCHAR) 

Current minute. 

seconds (UCHAR) 

Current second. 

hundredths (UCHAR) 

Current hundredth of a second. 

day (UCHAR) 

Current day. 

month (UCHAR) 

Current month. 

year (USHORT) 

Current year. 

timezone (SHORT) 

Minutes west of UTC (Universal Time Coordinate), 
weekday (UCHAR) 

Current day of the week. Sunday is 0. 

rc (USHORT) - return 

Return code description is: 

0 NO_ERROR 

Remarks 

The dayofweek value is based on Sunday equal to zero. The value of timezone is the difference in 
minutes between the current time zone and UTC. This number is positive if it is earlier than UTC and 
negative if it is later than UTC. For Eastern Standard Time, this value is 300 (5 hours earlier than UTC). 

If the application is executing in the OS/2 environment, it is more efficient to obtain these variables by 
calling DosGetlnfoSeg instead of this function. However, applications written to the family API cannot 
depend on the availability of DosGetlnfoSeg. 
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DosGetDateTime - 
Get Current Date and Time 


C Language 

typedef struct _DATETIME { /* date */ 

UCHAR hours; /* current hour */ 

UCHAR minutes; /* current minute */ 

UCHAR seconds; /* current second */ 

UCHAR hundredths; /* current hundredths of a second */ 

UCHAR day; /* current day */ 

UCHAR month; /* current month */ 

USHORT year; /* current year */ 

SHORT timezone; /* minutes of time west of UTC */ 

UCHAR weekday; /* current day of week */ 

} DATETIME; 

#define INCL_DOSDATETIME 

USHORT rc a DosGetDateTime(DateTime) ; 

PDATETIME DateTime; /* Address of date/time structure (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

DATETIME struc 

date_hours db ? ; current hour 

datejninutes db ? ; current minute 

date_seconds db ? ; current second 

datejiundredths db ? ; current hundredths of a second 
datejiay db ? ; current day 

datejnonth db ? ; current month 

date^year dw ? ; current year 

date_timezone dw ? ;minutes of time west of UTC 

date_weekday db ? ; current day of week 

DATETIME ends 

EXTRN DosGetDateTime: FAR 

INCL_DOSDATETIME EQU 1 

PUSH© OTHER DateTime ; Date/time structure (returned) 

CALL DosGetDateTime 

Returns WORD 

Example 

This example gets the current time and date. 

#define INCL_DOSDATETIME 

DATETIME DateBuffer; 

USHORT rc; 

rc s DosGetDateTime(&DateBuffer); /* Date/Time structure */ 
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DosGetDateTime - fapi 

Get Current Date and Time 


The following example obtains and prints date and time information. It then changes the system date to 
5/10/1987 and prints the updated information. 

Idefine INCL_DOSDATETIME 

linclude <os2.h> 

main() 

{ 

DATETIME DateTime; /* Structure to hold date/time info. */ 

USHORT rc; 

rc - DosGetDateTime(&DateTime); /* Address of d/t structure */ 
printf ("Today is %d-%d-%d; the time is %d:%d\n", DateTime. month, 

DateTime. day, DateTime. year, DateTime. hours, DateTime. minutes); 

DateTime. day = 10; 

DateTime. month - 5; 

DateTime. year = 1987; 

printf( H The new date is %d-%d-%d; the time is %d:%d\n M , DateTime. month, 

DateTime. day, DateTime. year, DateTime. hours, DateTime.minutes); 
rc = DosSetDateTime(&DateTime) ; /* Address of d/t structure */ 

printf("rc is %d\n", rc); 

} 
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FAPI 


DosGelDBCSEv - 
Get DBCS Environmental Vector 


This call obtains a DBCS (double byte character set) environmental vector that resides in the country 
information file. 


DosGetDBCSEv (Length, Country, MemoryBuffer) 


Parameters 

Length ( USHORT) - input 

Length, in bytes, of the data area (MemoryBuffer). This value should be at least 10. 

Country ( PCOUNTRYCODE ) - input 

Address of the country information structure: 

countrycode (USHORT) 

Country code identifier. 0 is the default country code, 
codepage (USHORT) 

Code page identifier. 0 is the code page of the current process. 

MemoryBuffer (PCHAR) - output 

Address of the country dependent information for the DBCS environmental vector. This memory 
area is provided by the caller. The size of the area is provided by the input parameter Length. If it is 
too small to hold all the available information, then as much information as possible is provided in 
the available space. The format of the information returned in this buffer is: 

Word Description 

1 First range definition for DBCS lead byte values 

High byte Binary start value (inclusive) for range one 

Low byte Binary stop value (inclusive) for range one. 

2 Second range definition 

High byte Binary start value for range two 
Low byte Binary stop value for range two. 

N Nth range definition 

High byte Binary start value for Nth range 

Low byte Binary stop value for Nth range. 

N + 1 Two bytes of binary 0 terminate list. 

For example: 

DB 81H.9FH 
DB EQH.FCH 
DB 00H.00H 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

396 ERROR_NLS_NO_COUNTRY_FILE 

397 ERROR_NLS_OPEN_FAILED 

398 ERROR_NO_COUNTRY_OR_CODEPAGE 

399 ERROR_NLS_TABLE_TRUNCATED 

Remarks 

The returned DBCS environmental vector may be for the default country and current process code page 
or for a specific country and code page. For more information on code page see “DosSetCp - Set 
Code Page” on page 2-320. 
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DosGetDBCSEv - 

Get DBCS Environmental Vector 


FAPI 


C Language 

typedef struct _COUNTRYC0DE { /* ctryc */ 

USHORT country; /* country code */ 

USHORT codepage; /* code page */ 

} COUNTRYCODE; 

Idefine INCL_DOSNLS 

USHORT rc « DosGetDBCSEv (Length, Structure, MemoryBuf fer) ; 

USHORT Length; /* Length of data area provided */ 

PCOUNTRYCODE Structure; /* Input data structure */ 

PCHAR MemoryBuffer; /* DBCS environmental vector (returned) * 

USHORT rc; /* return code */ 

Assembler Language 

COUNTRYCODE struc 

ctryc_country dw ? ;country code 
ctryc_codepage dw ? ;code page 

COUNTRYCODE ends 

EXTRN DosGetDBCSEv; FAR 
INCL_DOSNLS EQU 1 

PUSH WORD Length ; Length of data area provided 

PUSH® OTHER Structure ; Input data structure 

PUSH® OTHER MemoryBuffer ;DBCS environmental vector (returned) 

CALL DosGetDBCSEv 

Returns WORD 
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fapi DosGetEnv - 

Get Address of Process Environment String 


This call returns the address of the process environment string for the current process. 


DosGetEnv (EnvSegment, CmdOffset) 


Parameters 

EnvSegment (PSEL) - output 

Address of the selector for the environment segment. 

CmdOffset (PUSHORT) - output 

Address of the offset to the command line within the environment segment. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

12 E R ROR J N VALI D_ACCESS 

Remarks 

DosGetEnv can be used by dynamic link library routines that need to determine the environment for the 
current process. 

When a process issues DosExecPgm to start another process, the program that receives control is 
returned a pointer to the environment segment. 

C Language 

Idefine INCL.DOSMISC 

USHORT rc » DosGetEnv (EnvSegment, CmdOffset); 

PUSHORT EnvSegment; /* Selector (returned) */ 

PUSHORT CmdOffset; /* Command line offset (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosGetEnv: FAR 
I NCL_D0SMI SC EQU 1 

PUSH& WORD EnvSegment ; Selector (returned) 

PUSH@ WORD CmdOffset ; Command line offset (returned) 

CALL DosGetEnv 

Returns WORD 
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DosGetEnv - 

Get Address off Process Environment String 


FAPI 


Example 

The following example shows how one may obtain information for program initialization. The program 
locates the environment segment and prints the name of the command from the command line. It then 
obtains the OS/2 version number and prints it. 

Idefine INCL_D0$ 

#include <os2.h> 

Idefine ENVVARNAME “PATH" 
main() 


SEL 

EnvSel ; 

/* Environment segment selector (returned) */ 

USHORT 

CmdOffset ; 

/* Offset into env. seg. of command line (returned) */ 

PSZ FAR 

★Commandline; 

/* Pointer made by EnvSel and CmdOffset */ 

USHORT 

Version; 

/* Version numbers (returned) */ 

BYTE 

MajorVer; 

/★ Major version number */ 

BYTE 

MinorVer; 

/* Minor version number ★/ 

USHORT 

rc; 

/★ return code */ 


/** Locate environment segment and offset of command line. **/ 
if(!(rc c DosGetEnv(&EnvSel , /* Env. seg. selector (returned) */ 

SCmdOffset))) /* Offset of command line (returned) */ 
printf( "Environment located; selector is %x offset is %x\n‘\ EnvSel, 
CmdOffset); 

/** Use a macro to make a far pointer out of selector :offset pair. **/ 
/** Notice the far-string pointer specification (%Fs) used to print **/ 

Commandline - MAKEP ( EnvSel , CmdOffset); 

print f( "Command entered is %Fs.\n‘\ Commandline); 

/** Obtain and print version info; use macros to extract info. **/ 

/** We need to divide by 10 to obtain true version numbers. **/ 

i f ( ! (rc=DosGetVersi on(&Versi on) ) ) 

{ 

MajorVer = HIBYTE(Version) / 10; 

MinorVer = LOBYTE (Vers ion) / 10; 

printf("Thi s is OS/2 version %d.%d\n", MajorVer, MinorVer); 

} 
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FAPI 


DosGetHugeShift - 
Get Shift Count 


This call returns a shift count used to derive the selectors that address memory allocated with 
DosAllocHuge. 


DosGetHugeShift (ShlftCount) 


Parameters 

ShlftCount (PUSHORT) - output 
Address of the shift count. 

rc ( USHORT) - return 

Return code description is: 

0 NO_ERROR 

Remarks 

Each segment of a huge memory allocation has a unique selector. To compute the next sequential 
selector in a huge memory area, take the value 1, shift it left by the number of bits specified in shift count. 
Use the resulting value as an increment to add to the previous selector (using the selector returned by 
DosAllocHuge as the first selector). For example: 

• Assume DosAllocHuge is issued with NumSeg equal to 3, and that the number 63 is returned for the 
selector of the first segment. 

• If DosGetHugeShift returns a shift count of 4, shifting the value "I" by this amount results in an incre- 
ment of 16. 

• Adding this increment to selector number 63 produces 79 for the second selector. Adding the same 
increment to selector number 79 yields 95 for the third selector. 

C Language 

#define INCL_DOSMEMMGR 

USHORT rc = DosGetHugeShift (ShlftCount); 

PUSHORT ShiftCount; /* Shift Count (returned) */ 

USHORT rc; /* return code *7 

Assembler Language 

EXTRN DosGetHugeShift: FAR 
INCLJfOSMEMMGR EQU 1 

PUSH® WORD ShiftCount ; Shi ft Count (returned) 

CALL DosGetHugeShift 

Returns WORD 
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DosGetlnfoSeg - 

Get Address of System Variables Segment 


This call returns the address of a global and local information segment, specific to a process. 


DosGetlnfoSeg (GlobalSeg, LocalSeg) 


Parameters 

GlobalSeg (PSEL) - output 

Address of the global information segment structure, as defined below: 
time ( ULONG ) 

Time in seconds since 1/1/1970. 

mllllsecs (ULONG) 

Time in milliseconds. 

hours ( UCHAR ) 

Current hour. 

minute (UCHAR) 

Current minute. 

seconds (UCHAR) 

Current second. 

hundredsec (UCHAR) 

Current hundredth of a second. 

timezone (USHORT) 

Minutes from UTC; if hex FFFFH, timezone is undefined. 

Interval ( USHORT) 

Timer interval in tenths of milliseconds. 

day (UCHAR) 

Day. 

month (UCHAR) 

Month. 

year (USHORT) 

Year. 

weekday (UCHAR) 

Day-of-week: 

Value Definition 

0 Sunday 

1 Monday 

2 Tuesday 

3 Wednesday 

4 Thursday 

5 Friday 

6 Saturday 

majorverslon (UCHAR) 

Major version number. 

minorverslon (UCHAR) 

Minor version number. 

revision (UCHAR) 

Revision letter. 
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DosGetlnfoSeg - 

Get Address off System Variables Segment 


currentsession (UCHAR) 

Current foreground full-screen session. 

maxnumsessions (UCHAR) 

Maximum number of full-screen sessions. 

hugeshift (UCHAR) 

Shift count for huge segments. 

protmodeind (UCHAR) 

Protect-mode-only indicator: 

Value Definition 

0 DOS mode and OS/2 mode. 

1 OS/2 mode only. 

lastprocess (USHORT) 

Process ID of the current foreground process. 

dynvarflag (UCHAR) 

Dynamic variation flag: 

Value Definition 

0 Absolute 

1 Enabled. 

maxwait (UCHAR) 

Maximum wait in seconds. 

mintimesiice (USHORT) 

Minimum timeslice in milliseconds. 

maxtfmesilce (USHORT) 

Maximum timeslice in milliseconds. 

bootdrive (USHORT) 

Drive from which the system was booted: 

Value Definition 

1 Drive A. 

2 Drive Q. 


n Drive n. 

traceflags (UCHAR) 

32 system trace major code flags. Each bit corresponds to a trace major code, hex 00-FFH. The 
most significant bit (left-most) of the first byte corresponds to major code hex 00H. 

Value Definition 

0 Trace disabled. 

1 Trace enabled. 

maxtextsesslons (UCHAR) 

Maximum number of VIO windowable sessions. 

maxpmse88lons (UCHAR) 

Maximum number of Presentation Manager sessions. 

LocalSeg (PSEL) - output 

Address of the selector for the local information segment structure, as defined below: 

processid (PID) 

Current process ID. 

parentprocessid (PID) 

Parent process ID. 
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DosGetlnfoSeg - 

Get Address of System Variables Segment 


threadprty (USHORT) 

Priority of current thread. 

threadid (7/D) 

Current thread ID. 

sessionid ( USHORT) 

Current session ID. 

procstatus (UCHAR) 

Process status. 

unused (UCHAR) 

Unused. 

foregroundprocess (BOOL) 

Current process is in foreground (has keyboard focus). Value —1 implies yes, 0 implies no. 

typeProcess (UCHAR) 

Type of process: 

Value Definition 

0 Full screen protect mode session. 

1 Requires real mode. 

2 VIO windowable protect mode session. 

3 Presentation Manager protect mode session. 

4 Detached protect mode process. 

unused (UCHAR) 

Unused. 

environmentsel (SEL) 

Environment selector. 

cmdllneoff (USHORT) 

Command line offset in the segment addressed by environmentsel. 

dataseglen (USHORT) 

Length of data segment in bytes. 

stacksize (USHORT) 

Stack size in bytes. 

heapsize (USHORT) 

Heap size in bytes. 

hmodule (HMODULE) 

Module handle. 

dssel (SEL) 

Data segment selector. 

rc (USHORT) - return 

Return code description is: 

0 NOJERROR 

Remarks 

Items of general interest are kept in the global information segment. Items of information specific to a 
particular process are kept in the local information segment. This information can be directly read by the 
application program. Both of these segments are defined as read-only segments. The application 
program cannot modify this data. 

Assuming nl, n2, and n3 are the maximum number of full-screen sessions, VIO-windowable sessions, 
and Presentation Manager sessions, the first 0 through (nl — 1) session numbers are assigned to full- 
screen sessions. The next n2 session numbers are assigned to VIO-windowable sessions, and the next 
n3 session numbers are assigned to Presentation Manager sessions. Session numbers in the range 
(n1+n2+n3) through 255 are reserved. Applications should use (n1+n2+n3— 1) as an upper boundary. 
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DosGetlnfoSeg - 

Get Address of System Variables Segment 


Applications should not assume that all session numbers starting with (n1+n2) and higher are Presenta- 
tion Manager sessions. 

The application program must be careful when referencing the date or time fields in the global informa- 
tion segment. A timer interrupt can be received by the system in between the instructions that read the 
individual fields, changing the data in these fields. For example, if the time is currently 23:59:59 on 
Tuesday, 6/2/87, the program can read the hours field (23). A timer interrupt can now be received, 
changing the time to 00:00:00 on Wednesday, 6/3/87. The program reads the rest of the time field (0 
minutes) and the date field. The program would then think the current time and date is 23:00:00 on Wed- 
nesday, 6/3/87, which is incorrect. 

The application program should read all time and date fields it uses as quickly as possible. It can then 
compare the least significant time field it uses (milliseconds, hundredths, seconds, or minutes) against 
the current value in the global information segment. If the value has not changed, the rest of the informa- 
tion is valid. If the value has changed, the program time or date information should be read again, as the 
information is updated while the program reads it. 


C Language 

typedef struct _GINF0SEG { 


UL0NG 

time; 

/* time in seconds */ 

ULONG 

msecs; 

/* milliseconds */ 

UCHAR 

hour; 

/* hours */ 

UCHAR 

minutes; 

/* minutes */ 

UCHAR 

seconds; 

/* seconds */ 

UCHAR 

hundredths; 

/* hundredths */ 

USHORT 

tiraezone; 

/* minutes from UTC */ 

USH0RT 

cusecTimerlnterval ; 

/* timer interval (units = 0.0001 seconds) */ 

UCHAR 

day; 

/* day */ 

UCHAR 

month; 

/* month ie/ 

USHORT 

year; 

/ie year */ 

UCHAR 

weekday; 

/ie day of week */ 

UCHAR 

uchMajorVersion; 

/ie major version number ie/ 

UCHAR 

uchMinorVersion; 

/ie minor version number ie/ 

UCHAR 

chRevisionLetter; 

/ie revision letter ie/ 

UCHAR 

sgCurrent; 

/ie current foreground session ie/ 

UCHAR 

sgMax; 

/ie maximum number of sessions ie/ 

UCHAR 

cHugeShift; 

/ie shift count for huge elements */ 

UCHAR 

fProtectModeOnly; 

/ie protect mode only indicator ie/ 

USHORT 

pidForeground; 

/ie pid of last process in foreground session ie/ 

UCHAR 

f Dynami cSched ; 

/ie dynamic variation flag */ 

UCHAR 

csecMaxWait; 

/ie max wait in seconds ie/ 

USHORT 

cmsecMi nSlice; 

/ie minimum timeslice (milliseconds) ie/ 

USHORT 

cmsecMaxSlice; 

/ie maximum timeslice (milliseconds) ie/ 

USHORT 

bootdrive; 

/ie drive from which the system was booted */ 

UCHAR 

amecRAS [32] ; 

/ie system trace major code flag bits ie/ 

UCHAR 

csgWindowableVioMax;/* maximum number of VIO windowable sessions */ 

UCHAR 

csgPMMax; 

/ie maximum number of pres, services sessions ie/ 

} GINFOSEG; 
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DosGetlnfoSeg - 

Get Address of System Variables Segment 


typedef struct J.INF0SEG { 


PID 

pidCurrent; 

/* current process id */ 

PID 

pidParent; 

/* process id of parent */ 

USHORT 

prtyCurrent; 

/* priority of current thread */ 

TID 

tidCurrent; 

/* thread ID of current thread */ 

USHORT 

sgCurrent; 

/is session is/ 

UCHAR 

rfProcStatus; 

/is process status is/ 

UCHAR 

dummyl; 


BOOL 

f Foreground; 

/is current process has keyboard focus */ 

UCHAR 

typeProcess; 

/* process type ★/ 

UCHAR 

dummy2; 



SEL sel Environment; /* 

USHORT offCmdLi ne; /* 

USHORT cbDataSegment ; /* 

USHORT cbStack; /* 

USHORT cbHeap; /* 

HMODULE hmod; /* 

SEL selDS; /* 

} LINFOSEG; 


#define INCL_DOSINFOSEG 

USHORT rc = DosGetlnfoSeg (Global Seg, Local Seg); 

PSEL Global Seg; /* Address to place global segment (selector) */ 

PSEL Local Seg; /* Address to place local segment (selector) */ 

USHORT rc; /* return code */ 


environment selector */ 
command line offset */ 
length of data segment */ 
stack size */ 
heap size */ 

module handle of the application */ 
data segment handle of the application */ 


Assembler Language 


GINFOSEG st rue 

gi sjtime 

dd 

? 

gi sjnsecs 

dd 

? 

gis_hour 

db 

7 

gisjninutes 

db 

? 

gis_seconds 

db 

? 

gis_hundredths 

db 

? 

gis_timezone 

dw 

? 

gi s_cusecT i merlnterval 

dw 

? 

gis_day 

db 

? 

gis_month 

db 

7 

gis _year 

dw 

? 

gi s_weekday 

db 

? 

gi s_uchMajorVersi on 

db 

7 

gi s_uchMi norVersi on 

db 

? 

gi sjzhRevi si on Let ter 

db 

? 

gi s_sgCurrent 

db 

7 

gi s_sgMax 

db 

? 

gis_cHugeShi ft 

db 

? 

gi s_f ProtectModeOnly 

db 

? 

gisjpidForeground 

dw 

? 

gis_fDynamicSched 

db 

? 

gi s_csecMaxWai t 

db 

? 

gis^cmsecMinSlice 

dw 

7 

gis_cmsecMaxSlice 

dw 

? 

gis^bootdri ve 

dw 

? 

gis amecRAS 

db 

32 

gis_csgWindowableVioMax db 

7 

gi s_csgPMMax 

db 

? 


G1NF0SEG ends 


;time in seconds 
;milli seconds 
; hours 
; minutes 
; seconds 
; hundredths 
jminutes from UTC 

;timer interval (units = 0.0001 seconds) 

;day 

;month 

;year 

;day of week 

;major version number 

;minor version number 

; revision letter 

; current foreground session 

;maximum number of sessions 

; shift count for huge elements 

; protect mode only indicator 

;pid of last process in foreground session 

; dynamic variation flag 

;max wait in seconds 

jminimum times lice (milliseconds) 

jmaximum timeslice (milliseconds) 

; drive from which the system was booted 
dup (?) ;system trace major code flag bits 
; maxi mum number of VIO windowable sessions 
jmaximum number of pres, services sessions 
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DosGetlnfoSeg - 

Get Address of System Variables Segment 

LINFOSEG struc 

1 i s j>i dCurrent dw ? jcurrent process id 

1 i s j)i dParent dw ? ; process id of parent 

1 i s_prtyCurrent dw ? ; priority of current thread 

lis_ti dCurrent dw ? ; thread ID of current thread 
1 i s_sgCurrent dw ? ; session 

lis_rfProcStatus db ? ; process status 

lis_dumroyl db ? ; 

1 i s_f Foreground dw ? jcurrent process has keyboard focus 

lisJ:ypeProcess db ? ; process type 

lis_duimny2 db ? ; 

1is_s el Environment dw ? ; environment selector 

lis_offCmdLine dw ? ; command line offset 

1 i s_cbDataSegment dw ? ; length of data segment 

lis_cbStack dw ? ; stack size 

lis_cbHeap dw ? jheap size 

lis_hmod dw ? ; module handle of the application 

lis_selDS dw ? jdata segment handle of the application 

LINFOSEG ends 

EXTRN DosGetlnfoSeg: FAR 

INCL.DOSINFOSEG EQU 1 

PUSHO WORD Global Seg jGlobal segment selector (returned) 

PUSH? WORD Local Seg ; Local segment selector (returned) 

CALL DosGetlnfoSeg 

Returns WORD 
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DosGetMachineMode - 
Return Current Mode of Processor 


FA PI 


This call returns the current mode of the processor, whether the processor is running in the DOS mode or 
the OS/2 mode. This allows an application to determine whether a dynamic link call is valid or not. 


DosGetMachineMode (MachlneMode) 


Parameters 

MachlneMode (PBYTE) - output 

Address of the value to indicate the current processor mode. This value may be: 

Value Definition 

0 DOS mode 

1 OS/2 mode. 

rc ( USHORT) - return 

Return code description is: 

0 NO_ERROR 

Remarks 

All dynamic link calls are available to an application if the MachineMode value indicates the program is 
In OS/2 mode. This method provides a self-tailoring application that allows the application to adapt to the 
execution environment by limiting or enhancing the functions it provides. 

If the MachineMode value indicates the program is in DOS mode, the application is limited to a subset of 
dynamic link calls listed in the Family API. 

C Language 

#def i ne INCL_DOSQUEUES 

USHORT rc = DosGetMachineMode (MachineMode) ; 

PBYTE MachineMode; /* Processor mode (returned) */ 

USHORT rc; /* return code /*/ 

Assembler Language 

EXTRN DosGetMachi neMode ; FAR 
INCL.DOSQUEUES EQU 1 

PUSH@ BYTE MachineMode ; Processor mode (returned) 

CALL DosGetMachineMode 

Returns WORD 
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DosGetMessage - 

Retrieve System Message with Variable Text 


This call retrieves a message from a message file and inserts variable information into the body of the 
message. 


DosGetMessage (IvTable, IvCount, DataArea, DataLength, MsgNumber, FileName, 
MsgLength) 


Parameters 

IvTable ( PCHAR FAR *) - input 

Address of a list of double-word pointers. Each pointer points to an ASCIIZ or null-terminated DBCS 
string (variable insertion text). 0 to 9 strings can be present. 

IvCount (USHORT) - input 

Count of variable insertion text strings is 0—9. If IvCount is 0, IvTable is ignored. 

DataArea (PCHAR) - output 

Address of the requested message. If the message is too long to fit in the caller’s buffer, as much of 
the message text is returned as possible, with the appropriate error return code. 

DataLength ( USHORT) - input 

Length, in bytes, of the user’s storage area. 

MsgNumber (USHORT) - input 
Requested message number. 

FileName (PSZ) - input 

Address of the optional drive, path, and filename of the file where the message can be found. If mes- 
sages are bound to the .EXE file using MSGBIND utility, then filename is the name of the message 
file from which the messages are extracted. 

MsgLength (PUSHORT) — output 

Address of the length, in bytes, of the message. 

rc (USHORT) - return 


Return code 

i descriptions are: 

0 

NO_ERROR 

2 

ERROR_FILE_NOT_FOUND 

206 

ERROR_FILENAME_EXCED_RANGE 

316 

E R ROR_M R_MSG JT 00 _LONG 

317 

ERROR_M R_M 1 D_NOT_FOUND 

318 

ERROR_MR_UN_ACC_MSGF 

319 

ERROR_MRJNV_MSFG_FORMAT 

320 

ERROR_MRJNVJVCOUNT 

321 

ERROR_MR_UN_PERFORM 


Remarks 

If IvCount is greater than 9, DosGetMessage returns an error that indicates IvCount is out of range. If the 
numeric value of x in the %x sequence for %1through%9 is less than or equal to IvCount, text insertion 
by substitution for %x, is performed for all occurrences of %x in the message. Otherwise text insertion 
is ignored and the %x sequence is returned in the message unchanged. Text insertion is performed for 
all text strings defined by IvCount and IvTable. 

Variable data insertion is not dependent on blank character delimiters nor are blanks automatically 
inserted. 

For warning and error messages, the message ID (seven alphanumeric characters consisting of three 
upper case characters as the component ID, concatenated with a four-digit message number) followed by 
a colon and a blank character are returned to the caller as part of the message text. (DosGetMessage 
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DosGetMessage - 

Retrieve System Message with Variable Text 


determines the type of message based on the message classification generated in the output file of the 
MKMSGF utility.) 

The following is an example of a sample error message returned with the message ID: 

SYSO1O0: File not found 

DosGetMessage retrieves messages previously prepared by the utility MKMSGF to create a message 
file, or MSGBIND to bind a message segment to an .EXE file. DosGetMessage tries to retrieve the 
message from RAM in the message segment bound to the .EXE program. If the message cannot be 
found, DosGetMessage retrieves the message from the message file on DASD (direct access storage 
device, such as a diskette or fixed-disk). 

If the file name is not a fully-qualified name, DosGetMessage searches the following directories for 
default drive and path: 

• The system root directory 

• The current working directory 

• Directories listed in the DPATH statement (OS/2 mode only) 

• Directories listed in the APPEND statement (DOS mode only). 

If a message cannot be retrieved because of a DASD error or file not found condition, a default message 
is placed in the user’s buffer area. A message is placed in the buffer area based on the following error 
conditions: 

• The message number cannot be found in the message file. 

• The message file cannot be found. 

• The system detected a disk error trying to access the message file, or the message file format is 
incorrect. 

• IvCount is out of range. 

• A system error occurred trying to allocate storage. 

When these conditions occur, the default message allows the application program to issue a message 
and prompt that enables recovery opportunity. 

The residency of the message in RAM (EXE bound) or on DASD is transparent to the caller and handled 
by DosGetMessage. In either case the message is referenced by message number and file name. 

In order for DosGetMessage to be properly resolved, an application must be linked with DOSCALLS.L1B. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction 
applies to DosGetMessage when coding for the DOS mode: 

If the message file name is not a fully qualified name, DosGetMessage searches the root directory of the 
default drive for the message file, instead of the root directory of the startup drive. 

C Language 

#define INCL_DOSMISC 


USHORT rc = DosGetMessage(IvTable, IvCount, DataArea, DataLength, 

MsgNumber, FileName, MsgLength); 


PCHAR FAR * 

IvTable; 

/* Table of variables to insert */ 

USHORT 

IvCount; 

/* Number of variables */ 

PCHAR 

DataArea; 

/* Message buffer (returned) */ 

USHORT 

DataLength; 

/* Length of buffer */ 

USHORT 

MsgNumber; 

/* Number of the message */ 

PSZ 

FileName; 

fie Message file path name string ief 

PUSHORT 

MsgLength; 

fie Length of message (returned) */ 

USHORT 

rc; 

fie return code */ 
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Retrieve System Message with Variable Text 


Assembler Language 

EXTRN DosGetMessage: FAR 
INCLJ30SMISC EQU 1 

PUSH® OTHER I viable ; Table of variables to insert 

PUSH WORD IvCount ; Number of variables 

PUSH® OTHER DataArea ;Message buffer (returned) 

PUSH WORD DataLength ; Length of buffer 

PUSH WORD MsgNumber {Number of the message 

PUSH® ASCI IZ FileName {Message file path name string 

PUSH® WORD MsgLength {Length of message (returned) 

CALL DosGetMessage 


Returns WORD 
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DosGetModHandle - 

Get Dynamic Link Module Handle 


This call returns a handle to a previously loaded dynamic link module. 


DosGetModHandle (ModuleName, ModuleHandle) 


Parameters 

ModuleName ( PSZ ) - input 

Address of the ASCIIZ name string containing the dynamic link module name or the pathname string. 
The filename extension used for dynamic link libraries when a module name is provided is .DLL. 
When a pathname is provided, the module name may have any extension. 

ModuleHandle (PH MODULE) - output 

Address of the handle for the dynamic link module. 

re (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

95 ERRORJNTERRUPT 

123 ERRORJNVALID_NAME 

126 ERROR_MOD_NOT_FOUND 

Remarks 

If a module name is provided, it must match the name of a module residing in the LIBPATH that is cur- 
rently loaded. Otherwise an error code is returned. If a pathname is provided, the expanded pathname 
must match the full pathname of a module that is currently loaded. 

The handle returned by this call can be used with DosGetModName. It should not be used with 
DosGetProcAddr for access to the already loaded dynamic link module. Instead, DosLoadModule should 
be issued to ensure that the calling process is attached to the module. 

C Language 

#define INCL_DOSMODULEMGR 

USHORT rc = DosGetModHandle (ModuleName, ModuleHandle); 

PSZ ModuleName; /* Module name string */ 

PHMODULE ModuleHandle; /* Module handle (returned) it/ 

USHORT rc; /it return code it/ 

Assembler Language 

EXTRN DosGetModHandle; FAR 
INCL.DOSMODULEMGR EQU 1 

PUSH? ASCIIZ ModuleName ;Module name string 
PUSH? WORD ModuleHandle ;Module handle (returned) 

CALL DosGetModHandle 

Returns WORD 
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DosGetModName - 
Get Dynamic Link Module Name 


This call returns the fully qualified drive, path, file name, and extension associated with a referenced 
module handle. 


DosGetModName (ModuleHandle, BufferLength, Buffer) 

Parameters 

ModuleHandle ( HMODULE ) - input 

Handle of the dynamic link module being referenced. 

BufferLength (USHORT) - input 

Maximum length of the buffer, in bytes, where the name is stored. 

Buffer (PCHAR) - output 

Address of the buffer where the fully qualified drive, path, filename, and extension of the dynamic 
link module are stored. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

6 ERROR_INVALID_HANDLE 

24 ERROR_BAD_LENGTH 

95 ERRORJNTERRUPT 

Remarks 

The handle returned by either a DosGetModHandle or a DosLoadModule request can be used with this 
call. An error is returned if the buffer is not large enough for the module name. 

C Language 

# define INCLJJOSMODULEMGR 

USHORT rc = DosGetModName (ModuleHandle, BufferLength, Buffer); 

HMODULE ModuleHandle; /* Module handle */ 

USHORT BufferLength; /* Buffer length */ 

PCHAR Buffer; /* Buffer (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosGetModName : FAR 
INCL_DOSMODULEMGR EQU 1 

PUSH WORD ModuleHandle ; Module handle 
PUSH WORD BufferLength ; Buffer length 
PUSH? OTHER Buffer ; Buffer (returned) 

CALL DosGetModName 

Returns WORD 
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DosGetPID - 
Return Process ID 


FAPI 


This call returns the current process ID t thread ID, and the process ID of the parent process. 


DosGetPID (ProcessIDs) 


Parameters 

ProcessIDs (PPIDINFO) — output 

Address of the structure where the ID Information is returned. 

pld (PID) 

Current process identifier, 
tid (770) 

Thread (of the current process) identifier. 
pidParent (P/0) 

Parent process (of the current process) Identifier. 

rc ( USHORT) - return 

Return code description is: 

0 NO_ERROR 

Remarks 

The process ID may be used to generate uniquely named temporary files, or for communication with 
signals. For more information on signals, see DosFlagProcess and DosSendSignal. 

In the OS/2 environment, thread IDs are used with calls that manipulate threads in the current process. 
For more information, see DosSuspendThread, DosResumeThread, DosGetPrty, and DosSetPrty. 

If the application is executing in the OS/2 environment, it is more efficient to obtain these variables by 
calling DosGetlnfoSeg instead of DosGetPID. However, applications written to the family API cannot 
depend on the availability of DosGetlnfoSeg. 

To get an ID for a process other than the current process or its parent process, issue DosGetPPID. 

C Language 

typedef struct _PIDINF0 { /* pi di */ 

PID pid; /* current process' process ID */ 

TID tid; /* current process' thread ID */ 

PID pidParent; /* process ID of the parent */ 

} PIDINFO; 

#define INCL_DOSPROCESS 
USHORT rc = DosGetPID(ProcessIDsArea) ; 

PPIDINFO Process I DsArea; /* Process IDs 

USHORT rc; /* return code 


(returned) */ 
*/ 
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FAPI 


DosGetPID - 
Return Process ID 


Assembler Language 

PIDINFO strue 

pidi_pid dvr ? ; current process' process ID 

pidi_tid dvr ? ; current process' thread ID 

pidi_pidParent dw ? ; process ID of the parent 

PIDINFO ends 

EXTRN DosGetPID: FAR 
INCL.DOSPROCESS EQU 1 

PUSH® OTHER Process I DsArea ; Process IDs (returned) 
CALL DosGetPID 

Returns NONE 


Example 

The following example demonstrates how to create a process, obtain process ID information, and kill a 
process, Processl invokes process2 to run asynchronously. It obtains and prints some PID information, 
and then kills process2. 
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DosGetPID - 
Return Process ID 


/* processl.c */ 

Idefine INCL_DOSPROCESS 
# include <os2.h> 


Idefine START_PROGRAM "process2.exe" /* Program pointer */ 

main() 

{ 


CHAR 

Obj Fail [50]; 

fit Object name buffer itf 

RESULTCODES 

ReturnCodes; 

f* 

PIDINFO 

Pidlnfo; 


PID 

ParentID; 

/* 

USHORT 

rc; 



printf(" Process 1 now running. \n“); 


/** Start a child process. **/ 
if (! (DosExecPgm(0bjFai1 , 

sizeof(0bj Fail), 
EXEC ASYNC, 

NULL, 

NULL, 

SReturnCodes, 
START_PROGRAM))) 
printf("Process2 started. \n"); 


/* Object name buffer */ 

/* Length of obj. name buffer */ 

/* Execution flag - asynchronous */ 

/* No args. to pass to process2*/ 

/* Process2 inherits processl's environment */ 
/* Ptr. to resultcodes struct. */ 

/* Name of program file */ 


/** Obtain Process ID information and print it **/ 
if(!(rc=DosGetPID(&PidInfo))) /* Process ID's (returned) */ 
printf("DosGetPID: current process ID is %d; thread ID is %d; parent process ID is %d.\n", 
Pidlnfo.pid, Pidlnfo.tid, Pidlnfo.pidParent) ; 
if (! (rc=DosGetPPID( 

Ret urnCodes . codeT ermi nate , /* Process whose parent is wanted */ 

SParentlD))) /* Address to put parent's PID */ 

printf ("Child process ID is %d; Parent process ID is %d.\n". 

Ret urnCodes .codeTermi nate, Parent ID) ; 


/** Terminate process2 **/ 

i f ( ! (rc=DosKi 1 1 Process (DKP_PROCESSTREE, /* Action code - kill process and descendants */ 

ReturnCodes.codeTerminate))) /* PID of root of process tree */ 
printf ("Process2 terminated by processl.\n") ; 


} 


/* process2.c */ 

#define INCLJOSPROCESS 
#include <os2.h> 


#define SLEEPTIME 5G0L 
#define RETURN_CODE 0 


main() 

{ 

printf ("Process2 now running.\n"); 


fit Sleep to allow processl to kill 
DosSl eep(SLEEPTIME) ; 

DosExi t ( EXIT_PROCESS , 

RETURN_CODE) ; 


it */ 

/* Sleep interval It/ 
fit Action Code itf 
fit Result Code itf 


FAPI 
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DosGetPPID - 
Get a Process’s Parent’s PID 


This call allows the caller to obtain the parent process ID for any process. 


DosGetPPID (PID, PPID) 


Parameters 

PID (USHORT) - input 

The process ID of the process to find the parent PID. 

PPID (PUSHORT) - output 

Address of a word where the process ID of the parent of the indicated process is placed. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

303 ERROR_INVALID_PROCID 


C Language 

Idefine INCLJJOSPROCESS 

USHORT rc = DosGetPPID(PID, PPID); 


USHORT 

PID; 

/* Process whose parent is 

wanted ief 

PUSHORT 

PPID; 

fie Address to put parent's 

PID ief 

USHORT 

rc; 

fie return code ief 



Assembler Language 

EXTRN DosGetPPID:FAR 
INCLJJOSPROCESS EQU 1 

PUSH WORD PID ; Process whose parent is wanted 

PUSHta WORD PPID jAddress to put parent’s PID 

CALL DosGetPPID 

Returns NONE 

Example 

The following example demonstrates how to create a process, obtain process ID information, and kill a 
process. Processl invokes process2 to run asynchronously. It obtains and prints some PID information, 
and then kills process2. 
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DosGetPPID - 

Get a Process’s Parent’s PID 


/* process l.c */ 

Idefine INCL_DOSPROCESS 
#include <os2.h> 


Idefine START_PROGRAM "process2.exe" /* Program pointer */ 


iin() 

CHAR 

ObjFail [50]; 

/k Object name buffer k/ 

RESULTCODES 

ReturnCodes; 

/* 

PIDINFO 

Pidlnfo; 


PID 

ParentID; 

/* 

USHORT 

rc; 



printf ("Processl now running. \n"); 

/** Start a child process, irk/ 
i f ( i (DosExecPgm(Obj Fai 1 , 

sizeof (ObjFail) , 

EXEC ASYNC, 

NULL, 

NULL, 

&ReturnCodes, 

START.PROGRAM))) 
printf("Process2 started. \n H ); 

/kk Obtain Process ID information and print it kk/ 
if (! (rc=DosGetPID(&PidInfo))) /k Process ID's (returned) k/ 
printf ("DosGetPID: current process ID is %d; thread ID is %d; parent process ID is %d.\n", 
Pidlnfo.pid, Pidlnfo.tid, Pidlnfo.pidParent) ; 
if(!(rc=DosGetPPID( 

ReturnCodes.codeTerminate, fk Process whose parent is wanted */ 

&ParentID))) /* Address to put parent's PID k/ 

printf ("Child process ID is %d; Parent process ID is %d,\n", 

ReturnCodes.ccdeTerminate, ParentID) ; 

/kk Terminate process2 kk/ 

if (! (rc=DosKi 11 Process (DKP_PROCESSTREE, /k Action code - kill process and descendants kf 
ReturnCodes.codeTerminate))) /k PID of root of process tree k/ 
printf ("Process2 terminated by processl.\n H ); 

} 

/k process2.c k/ 

#def i ne INCL_DOSPROCESS 

#include <os2.h> 

#define SLEEPTIME 500L 
#define RETURN_CODE 0 

main() 

{ 

printf ("Process2 now running.\n"); 

/k Sleep to allow processl to kill it */ 

DosSl eep (SLEEPTIME) ; /k Sleep interval k/ 

DosExit(EXlT_PROCESS, /k Action Code k/ 

RETURN^CODE); /k Result Code k/ 

) 


/k Object name buffer k/ 

/k Length of obj. name buffer k/ 

/k Execution flag - asynchronous k/ 

/k No args. to pass to process2*/ 

/k Process2 inherits processl* s environment k/ 
/k Ptr, to resultcodes struct, k/ 

/k Name of program file k/ 
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DosGetProcAddr - 
Get Dynamic Link Procedure Address 


This call returns a far address to a desired procedure within a dynamic link module. 


DosGetProcAddr (ModuleHandle, ProcName, ProcAddress) 


Parameters 

ModuleHandle ( HMODULE ) - input 
Handle of the dynamic link module. 

ProcName ( PSZ ) - input 

Address of a name string that contains the referenced procedure name. 

Alternatively, if the selector portion of the pointer is null, the offset portion of the pointer is an explicit 
entry number (ordinal) within the dynamic link module. 

DosGetProcAddr for entries within the DOSCALLS module are only supported for ordinal references. 
References to the DOSCALLS module by name strings are not supported and return an error. 
Dynamic link ordinal numbers for DOSCALLS routines are resolved by linking with DOSCALLS.LIB. 

ProcAddress (PFN FAR *) - output 
Procedure address. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERROR JNVALID_H AN DLE 

95 ERRORJNTERRUPT 

127 ERROR_PROC_NOT_FOUND 


Remarks 

A 32-bit address, consisting of a selector and offset, is returned for a specified procedure. 

To free the dynamic link module, issue DosFreeModule. After DosFreeModule is issued, procedure entry 
addresses returned for this handle or no longer valid. 

Other run-time dynamic link calls are DosLoadModule, DosGetModName, and DosGetModHandle. 


C Language 

#define I NCL_DOSMODULEMGR 

USHORT rc = DosGetProcAddr(McduleHandle, ProcName, ProcAddress); 


HMODULE 

PSZ 

PFN FAR * 


ModuleHandle; /* Module handle */ 

ProcName; /* Module name string */ 

ProcAddress; /* Procedure address (returned) it/ 


USHORT rc; 


/it return code */ 


Assembler Language 

EXTRN DosGetProcAddr: FAR 

I NCL_D0$M0DU LEMGR EQU 1 

PUSH WORD ModuleHandle ;Module handle 

PUSH® ASCI IZ ProcName ;Module name string 

PUSH0 DWORD ProcAddress procedure address (returned) 

CALL DosGetProcAddr 

Returns WORD 
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DosGetPrty - 
Get Process’s Priority 


This call gets the priority of the initial thread of execution for any process, or any thread in the current 
process. 


DosGetPrty (Scope, Priority, ID) 


Parameters 

Scope (USHORT) — input 

Scope of priority request. Used to define the scope of the request. 

Value Definition 

0 Thread 1 (the initial thread of execution) of the indicated process. 

2 Any thread of the current process. 

Priority (PUSHORT) - output 

Address of the base priority of the thread identified by ID. The high-order byte of this word is set 
equal to the priority class. The low-order byte is set equal to the priority level. 

ID ( USHORT) - input 

A process ID (scope = 0) or a thread ID (scope = 2). If this operand is equal to 0, the current 
process or thread is assumed. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NOERROR 

303 ERROR JNVALIDPROCID 

308 ERRORJNVALIDSCOPE 

309 ERRORJNVALID_THREADID 

Remarks 

If scope = 0 (process) the priority of the first thread of a process is returned. If that thread has termi- 
nated, the ERRORJNVALID_THREADJD error code is returned. 

A thread’s priority is changed by issuing DosSetPrty. A process can change the priority of all the threads 
of any process whose process ID is known to the thread. It can also change the priority of another thread 
in its process, or all the threads of the current or a child process, as well as all its descendants. 

DosGetPID and DosGetPPID are useful for obtaining process and thread IDs. DosGetPID gets the ID of the 
current thread, the process ID of its current process, or the process ID of the parent process of the 
current process. DosGetPPID gets the parent process ID of any specified process. 

C Language 

Idefine INCL_DOSPROCESS 


USHORT rc = DosGetPrty (Scope, Priority, ID); 


USHORT 

Scope; 

/* Indicate scope of query */ 

PUSHORT 

Priority; 

/* Address to put priority (returned) */ 

USHORT 

ID; 

/* Process or thread ID if/ 

USHORT 

rc; 

/if return code */ 
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DosGetPrty - 
Get Process’s Priority 


Assembler Language 

EXTRN DosGetPrty: FAR 
INCL_DOSPROCESS EQU 1 

PUSH WORD Scope ; Indicate scope of query 

PUSHO WORD Priority priority (returned) 

PUSH WORD ID ; Process or thread ID 

CALL DosGetPrty 

Returns WORD 

Example 

The following example illustrates how to obtain the priority of a thread and how to change the priority. 
The main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that 
prints a line and then sleeps, relinquishing its time slice to the main thread. After one or two iterations 
by Thread2, the main thread obtains Thread2's priority information and prints it. It then raises Thread2's 
priority to fixed-high, and increments the level by ten. Since Thread2 is now at a high priority, it imme- 
diately finishes its remaining iterations before relinquishing control on a long sleep; at this point, the 
main thread re-examines Thread2's priority and reports its new priority level. In this example, it is 
helpful to understand how the DosSleep calls are used either to relinquish control of the processor, or to 
keep a thread alive (see DosTimerAsync or DosTimerStart for alternatives to DosSleep). 

#define INCL_D0SPR0CE$S 
linclude <os2.h> 


Idefine 

PRTYC FIXEDHIGH 

4 

/* Priority class: fixed-high */ 

Idef i ne 

PRTY DELTA 

10 

/* Priority delta: increase by 10 */ 

Idefine 

SEGSIZE 

4000 

/* Number of bytes requested in segment */ 

Idefine 

ALLOCFLAGS 

0 

/* Segment allocation flags - no sharing ie/ 

Idefine 

SLEEPSHORT 

0L 

/* Sleep interval - 5 milliseconds ie/ 

Idefine 

SLEEPLONG 

20L 

fie Sleep interval - 75 milliseconds iej 

Idefine 

RETURN CODE 

0 

fie Return code for DosExitQ iej 


VOID API ENTRY Thread2() 

{ 

USHORT i ; 

/* Loop with four iterations */ 
for(i=l; i<5; i++) 

{ 

printf("In Thread2, i is now %d\n% i); 

/** Sleep to relinquish time slice to main thread **/ 
DosSleep(SLEEPSHORT) ; /* Sleep interval */ 

} 

Dos Exi t ( EX I T_THRE AD , /* Action code - end a thread */ 

RETURN CODE); /* Return code */ 

} 
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DosGetPrty - 
Get Process’s Priority 


main{) 


USHORT 

Priority; 

/it Thread priority it/ 

USHORT 

Class; 

/it Priority class it/ 

USHORT 

Level ; 

/it Priority level it/ 

SEL 

ThreadStackSel ; 

fit Segment selector for thread stack it/ 

PBYTE 

StackEnd; 

/it Ptr. to end of thread stack it/ 

USHORT 

rc; 



/* Allocate segment for thread stack; this is better than just */ 

/it declaring an array of bytes to use as a stack. Make pointer eos. it/ 


rc = DosAl 1 ocSeg (SEGSIZE , 

AThreadStackSel * 
ALLOCFLAGS) ; 

StackEnd = MAKEP(ThreadStackSel , SEGSIZE- 
/* Start Thread2 it/ 

i f ( ! ( DosCreateThread ( ( PFNTHREAD) Thread2, 
AThreadlD, 
StackEnd))) 
printfCThreadZ created. \n ") ; 


/it Number of bytes requested */ 
fit Segment selector (returned) */ 
/it Allocation flags it/ 


/•k Thread address */ 

/it Thread 10 (returned) it/ 
/it End of thread stack it/ 


fitit Sleep to allow Thread2 to execute itit/ 

1 f ( ! (OosSl eep (SLEEPLONG) ) ) fit Sleep interval it/ 

printf( "Slept a little to let Thread2 execute. \n“); 


/itit Obtain Thread2's priority information and report it **/ 
if(!(rc=DosGetPrty(PRTYS_THREAD, /it Scope - single thread */ 

Apriority, /* Address to put priority */ 

ThreadID))) fit ID - thread ID it/ 

{ 


/it Extract priority class and level information it/ 

Class = HIBYTE (Priori ty) ; 

Level = LOBYTE (Priority) ; 

printf ( M Thread2: ID is %d. Priority Class is %d and Level is %d\n". 


ThreadID, Class, Level); 

} 

/** Raise Thread2's priority itit/ 
i f ( ! ( rc=Dos Set Prty ( PRTYS_THRE AD , 

PRTYC FIXEDHIGH, 

PRTY_DELTA, 

ThreadID))) 

{ 


fit Scope - single thread */ 

/it Prty class - fixed-high it/ 

/it Prty delta - increase by 10 */ 
/* ID - thread ID it/ 


/it Obtain Thread2' new priority information and report it */ 
r c=DosGet Prty ( PRTYSJTHREAD , /it Scope - single thread it/ 

APriority, /it Address to put priority it/ 

ThreadID); /it ID - thread ID it/ 


/it Extract priority class and level information */ 

Class = HIBYTE(Priority); 

Level * LOBYTE (Priority); 

printf ("Thread2: ID is %d. New Priority Class is %d and Level is %d\n", 
ThreadID, Class, Level); 

} 

} 
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DosGetResource - 
Get Resource Segment Selector 


This call returns the segment selector of the specified resource segment. 


DosGetResource (ModHandle, TypelD, NamelD, Selector) 


Parameters 

ModHandle ( HMODULE ) - input 

The location of the resource segment. 

Value Definition 

0 The executable file of the current process. 

^0 A handle to a dynamic link module returned by DosLoadModule. 

TypelD (USHORT) - input 

A 16 bit resource type ID (see Remarks). 

NamelD ( USHORT) - input 

A 16 bit resource name ID (see Remarks). 

Selector ( PSEL ) - output 

The address of a word where the resource segment selector is returned. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

Remarks 

Resource segments are read-only data segments that can be accessed dynamically at run time. The 
access key consists of two 16-bit numbers, the first of which is a type ID and the second, a name ID. 

These numbers are similar in concept to the file extension and file name portions of a file name. 

The advantage of resource segments is that they can be bundled into an application’s executable file, so 
a single file contains all of the code and data for an application. 

It is recommended that resource segments obtained through DosGetResource only be freed using 
DosFreeSeg. 

OS/2 Version 1.2 added two new functions, DosGetResource2 and DosFreeResource, to load and free an 
application specific resource. DosGetResource2 returns a far pointer to a resource rather than the 
selector returned via DosGetResource. It is recommended that applications targeted for OS/2 1.2 use 
DosGetResource2 and DosFreeResource. Applications that wish to execute on OS/2 1.1 and 1.2 should 
use the OS/2 run-time dynamic link capabilities, DosLoadModule and DosGetProcAddr, to get the address 
of DosGetResource2 and DosFreeResource when executing on OS/2 1.2. If the DosGetProcAddr call to 
obtain the address of DosGetResource2 and DosFreeResource fails, the application can call 
DosGetResource and DosFreeSeg. Applications that use DosGetResource2 and DosFreeResource allow 
OS/2 to optimize memory allocation associated with the applications resource. 
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DosGetResource - 

Get Resource Segment Selector 


C Language 

ifdefine INCL_DOSRESOURCES 

USHORT rc = DosGetResource(ModHandle, TypelD, NamelD, Selector); 


MODULE 

USHORT 

USHORT 

PSEL 

ModHandle; 
Type ID; 
NamelD; 
Selector; 

/* Module handle to get resource from */ 
/* 16 bit resource type ID */ 

1 * 16 bit resource name ID */ 

/* where to return selector */ 

USHORT 

rc; 

/* return code */ 

Assembler Language 

EXTRN DosGetResource : FAR 
INCL_DO$RESOURCES EQU 1 


PUSH WORD ModHandle 

PUSH WORD Type ID 

PUSH WORD NamelD 

PUSH0 WORD Selector 

CALL DosGetResource 

Module handle to get resource from 

16 bit resource type ID 

16 bit resource name ID 

Resource selector (returned) 


Returns WORD 
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DosGetResource2 - 
Get Resource Address 


This call returns the far address of the specified resource. 


DosGetResource2 (ModHandle, TypelD, NamelD, ResAddr) 


Parameters 

ModHandle ( HMODULE ) - input 
The location of the resource. 

Value Definition 

0 The executable file of the current process. 

^0 A handle to a dynamic link module returned by DosLoadModule. 

TypelD ( USHORT) - input 

A 16 bit resource type ID (see Remarks). 

NamelD (USHORT) - input 

A 16 bit resource name ID (see Remarks). 

ResAddr (PULONG) - output 

Address of the resource address. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERRORJNVALID_HANDLE 

Remarks 

A resource is read-only data generated by the Resource Compiler that can be accessed dynamically at 
run time. The access key consists of two 16-bit numbers, the first of which is a type ID and the second, a 
name ID. These numbers are similar in concept to the file extension and file name portions of a file 
name. 

The advantage of a resource is that it can be bundled into an application’s executable file, so a single file 
contains all of the code and data for an application. 

Resource segments obtained through DosGetResource2 should only be freed using DosFreeResource. 


C Language 

Idefine INCL_D0SRE$0URCES2 

USHORT rc * DosGetResource2 (ModHandle, TypelD, NamelD, ResAddr); 


HMODULE 

ModHandle; 

/* Module handle to get resource from */ 

USHORT 

TypelD; 

/* 16 bit resource type ID */ 

USHORT 

NamelD; 

/* 16 bit resource name ID */ 

PULONG 

ResAddr; 

/* where to return resource address */ 

USHORT 

rc; 

/★ return code */ 
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DosGetResource2 - 
Get Resource Address 


Assembler Language 

EXTRN DosGetResource2 : FAR 
INCL_D0SRES0URCES2 EQU 1 


PUSH 

WORD 

ModHandle 

;Module handle to get resource from 

PUSH 

WORD 

TypelD 

; 16 bit resource type ID 

PUSH 

WORD 

Name ID 

; 16 bit resource name ID 

PUSH@ 

DWORD 

ResAddr 

; Resource address (returned) 


CALL DosGetResource2 
Returns WORD 
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DosGetSeg - 
Access Segment 


This call accesses shared memory allocated by a DosAllocSeg or DosAllocHuge call. 


DosGetSeg (Selector) 


Parameters 

Selector (SEL) - input 

Parameter used to get access to a segment. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

Remarks 

Before a process can call DosGetSeg to access shared memory allocated by a DosAllocSeg or 
DosAllocHuge request, it must be given a selector by the process that allocated the memory. The giving 
process obtains this selector by calling DosGiveSeg. It then passes the selector returned by DosGiveSeg 
to the recipient process, using some form of interprocess communication. If the recipient has created a 
queue with DosCreateQueue, the giving process can write the selector to the queue and then free the 
segment with a call to DosFreeSeg. The recipient removes the selector from the queue with a 
DosReadQueue and calls DosGetSeg, specifying the passed selector. 

If at the time the shared segment is allocated, it is also specified as discardable, it is automatically 
locked for access by the caller. The caller may free the segment for discard by a DoslInlockSeg call. A 
process that gains access to the discardable shared segment by calling DosGetSeg has to lock the 
segment with a DosLockSeg request. However, DosLockSeg may return an error, indicating the segment 
is already locked. In this case, the process calls DoslInlockSeg repetitively, until the segment is fully 
unlocked. The process then locks the segment for its own use. Locking is an attribute of the segment, 
not the processes using the segment. 

To access named shared memory allocated with a DosAllocShrSeg request, a process issues 
DosGetShrSeg. 

C Language 

Idefine INCL_DOSMEMMGR 

USHORT rc « DosGetSeg(Selector); 

SEL Selector; /^Selector to access */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosGetSeg: FAR 
INCL.DOSMEMHGR EQU 1 

PUSH WORD Selector ; Selector to access 
CALL DosGetSeg 

Returns WORD 
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DosGetShrSeg - 
Access Shared Segment 


This call accesses a shared memory segment previously allocated by another process. 


DosGetShrSeg (Name, Selector) 


Parameters 

Name ( PSZ ) - input 

Address of the name string associated with the shared memory segment to be accessed. The name 
is an ASCIIZ string in the format of an OS/2 filename in a subdirectory called \SHAREMEM\, for 
example, \SHAREMEM\PUBLIC.DAT. 

Selector (PSEL) - output 

Address of the selector for the shared memory segment. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOTJFOUND 

4 ERROR_TOO_MANY_OPEN_FILES 

123 ERROR JNVALID_NAME 

Remarks 

DosGetShrSeg provides access to a named shared segment allocated by another process with 
DosAIIocShrSeg. The selector returned by DosGetShrSeg is the same as the one returned by the 
DosAllocShrSeg call. 

A usage count is maintained for a named shared segment. Issuing DosGetShrSeg increments the count, 
and issuing DosFreeSeg decrements the count. When the usage count equals zero, the named shared 
segment is deallocated. Once the segment has been deallocated, it must be reinitialized by a call to 
DosAIIocShrSeg. 

To access shared memory that is allocated by another process with DosAliocSeg and DosAllocHuge 
requests, a process issues DosGetSeg. 

C Language 

#define INCL_DO$MEMKGR 

USHORT rc = DosGetShrSeg (Name, Selector); 

PSZ Name; /* Name string 

PSEL Selector; /* Selector of 

USHORT rc; /* return code 

Assembler Language 

EXTRN DosGetShrSeg: FAR 
INCLJ)QSMEMMGR EQU 1 

PUSH® ASCIIZ Name ;Name string 

PUSH® WORD Selector ; Select or of shared segment (returned) 

CALL DosGetShrSeg 

Returns WORD 


*/ 

shared segment */ 
/* 
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FAPI 


DosGetVersion - 
Get OS/2 Version Number 


This call returns the OS/2 version number. 


DosGetVersion (VersionWord) 


Parameters 

VersionWord (PUSHORT) - output 

Address of the OS/2 version number. The version is stored as two bytes, with the minor version in 
the first byte and major version in the second byte. 

rc (USHORT) - return 

Return code description is: 

0 NO_ERROR 

C Language 

/define INCUWSMISC 

USHORT rc = DosGetVersi on( VersionWord) ; 

PUSHORT VersionWord; /* Version number (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosGetVersi on: FAR 
INCLJOSMISC EQU 1 

PUSH@ WORD VersionWord ; Version number (returned) 

CALL DosGetVersion 

Returns WORD 
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DosGetVersion - 
Get OS/2 Version Number 


FAPI 


Example 

The following example shows how one may obtain information for program initialization. The program 
locates the environment segment and prints the name of the command from the command line. It then 
obtains the OS/2 version number and prints it. 

Idefine INCL_D0S 
#include <o$2.h> 


Idefine ENVVARNAME "PATH" 


main() 

{ 

SEL 

EnvSel ; 

/* Environment segment selector (returned) */ 

USHORT 

CmdOffset; 

/★ Offset into env. seg. of command line (returned) ★/ 

PSZ FAR 

★Commandline; 

/* Pointer made by EnvSel and CmdOffset */ 

USHORT 

Version; 

/* Version numbers (returned) */ 

BYTE 

MajorVer; 

/* Major version number */ 

BYTE 

Mi norVer; 

/* Minor version number */ 

USHORT 

rc; 

/★ return code ★/ 


/** Locate environment segment and offset of command line. **/ 

if (! (rc-Do$GetEnv(&EnvSel . /* Env. seg. selector (returned) */ 

&CmdOffset))) /* Offset of command line (returned) */ 
printf(" Environment located; selector is %x offset is %x\n‘\ EnvSel, 
CmdOffset) ; 

/** Use a macro to make a far pointer out of selector; offset pair. **/ 
/** Notice the far-string pointer specification (%Fs) used to print ★*/ 

Commandline = MAKEP(Env$el , CmdOffset); 
printf( "Command entered is %Fs.\n", Commandline); 

/** Obtain and print version info; use macros to extract info. **/ 

/** We need to divide by 10 to obtain true version numbers. *★/ 

if (I (rc=DosGetVersion(&Version))) 

{ 

MajorVer = HIBYTE(Version) / 10; 

MinorVer = LOBYTE (Version) / 10; 

printf ("This is OS/2 version %d.%d\n", MajorVer* MinorVer); 

} 
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DosGiveSeg - 
Give Access to Segment 


This call allows another process to access shared memory allocated by a DosAllocSeg or DosAllocHuge 
call. 


DosGiveSeg (CallerSegSelector, ProcessID, RecfpientSegSelector) 


Parameters 

CallerSegSelector (SEL) - input 

Segment selector of the shared memory segment. 

ProcessID ( PID ) — input 

Process ID of the process to receive access to the shared memory segment. 

RecfpientSegSelector (PSEL) - output 

Address of the recipient's segment selector. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

5 ERROR_ACCESS_DENIED 

8 ERROR JMOT_ENOUGH_M EMORY 

Remarks 

DosGiveSeg returns a selector that can be given to another process to access shared memory the giver 
has allocated by a DosAllocSeg or DosAllocHuge call. The giving process passes the recipient's selector 
to the intended sharer by some means of interprocess communication. If the recipient has created a 
queue with DosCreateQueue, the giver can issue DosWriteQueue, specifying the queue name, and pass 
the selector in this manner. 

If the memory being given was allocated by a DosAllocHuge request, the CallerSegSelector must be the 
base selector returned by DosAllocHuge. When the caller passes the selector returned in 
RecipientSegSelector to the intended sharer, this selector has addressability only to the first segment in 
the sharer's address space of the huge allocation. However, the recipient can call DosGetHugeShift and 
use the shift count returned to calculate the selectors for the remaining segments. 

C Language 

#define INCLJJOSMEMMGR 

USHORT rc = DosGiveSeg (CallerSegSelector, ProcessID, RecipientSegSelector); 

SEL CallerSegSelector; /* Caller's segment selector */ 

PID ProcessID; /* Process ID of recipient */ 

PSEL RecipientSegSelector; /* Recipient's segment selector (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosGiveSeg: FAR 
INCL_DOSMEMMGR EQU 1 

PUSH WORD CallerSegSelector ; Caller's segment selector 

PUSH WORD ProcessID ; Process ID of recipient 

PUSH0 WORD RecipientSegSelector ;Recipient's segment selector (returned) 

CALL DosGiveSeg 

Returns WORD 
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DosHoldSignal - 
Disable/Enable Signals 


FAPI 


This call temporarily disables or enables signal processing for the current process. 


DosHoldSignal (ActlonCode) 


Parameters 

ActlonCode (USHORT) - input 

Disables or enables signals intended for the current process. 

Value Definition 

0 Signals are enabled 

1 Signals are disabled. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERRORJNVALID_FUNCTION 

Remarks 

DosHoldSignal with ActionCode = f causes signal processing (except central processing errors and 
numeric processor errors) to be postponed until a DosHoldSignal with ActionCode = 0 is issued. Any 
signals that occur while processing is disabled are recognized, but not accepted until signal recognition 
is enabled. 

To allow for nesting of requests, a count of the number of outstanding DosHoldSignal requests with 
ActionCode = 1 are maintained. 

DosHoldSignal is used by library routines, subsystems, and similar code that lock critical sections or 
temporarily reserve resources needed to prevent a signal from terminating a task. A process can have 
only one signal handling address for each signal. Dynalink routines should not have a signal handler 
(which might override a handler established by a calling process). 

Signals can be held for a short period and should be released and re-held, if necessary. Their guidelines 
for proper use are similar to hardware interrupt counterparts such as the CLI/STI instructions. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restriction applies to DosHoldSignal when coding for the DOS mode: 

The only signal recognized in the DOS mode is SIGINTR (Ctrl-C) and SIGBREAK. Only SIGINTR and 
SIGBREAK are turned off by this call. 

C Language 

Idefine INCLJJOSSIGNALS 
USHORT rc = DosHoldSignal (ActionCode); 

USHORT ActionCode; /* Indicate to 

USHORT rc; /* return code 


Disable/Enable Signals */ 
*/ 
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FAPI 


DosHoldSignal - 
Disable/Enable Signals 


Assembler Language 

EXTRN DosHoldSignal: FAR 
INCL_DO$$IGNALS EQU 1 

PUSH WORD ActionCode indicate to Disable/Enable Signals 
CALL DosHoldSignal 

Returns NONE 


Example 

The following example illustrates the use of the Ctrl-C (SIGINTR) signal to signal time-critical events. 
Processl invokes process2, which establishes a signal handier named CtrlCJHandler{) and waits, by 
blocking on a reserved RAM semaphore, for a signal from processl. A portion of process2 is immune to 
signalling. 

Idefine INCL.DOSPROCESS 
Idefine INCL_DOSSIGNALS 

linclude <os2.h> 

Idefine SLEEPTIME 20OL /* Sleep interval */ 

Idefine START_PROGRAM " process2.exe" /* Program name */ 


main() 

{ 

CHAR 

PSZ 

PSZ 

RESULTCODES 

USHORT 


QbjFailiSQ"; 

Args; 

Envs; 

ReturnCodes; 

rc; 


/* Start proce$s2 and check its 

PID */ 

i f ( 1 (DosExecPgm(Obj Fai 1 , 

/* 

sizeof (ObjFail), 

/* 

EXEC_ASYNC , 

/* 

Args, 

/* 

Envs, 

/* 

^ReturnCodes, 

/* 

START^PROGRAM))) 
print f(“Process2 started. \n“); 

/* 


name buffer */ 


to resultcodes struct. */ 


printf ("Process2 ID is %d\n", ReturnCodes. codeTermi nate) ; 


/* Sleep to give time slice to process2 */ 
DosSleep(SLEEPTIME) ; /* Sleep interval */ 


/*** After proce$$2 sets signal handler, send process2 a signal ***/ 
if(!(rc = DosSendSignal (ReturnCodes. codeTermi nate, /* PID of process2 */ 
SIG_CTRLC))) /* Signal to send */ 

printf ("Ctrl-C signal sent from Processl to Process2.\n“); 

} 
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DosHoldSignal - 
Disable/Enable Signals 


FAPI 


/* process2.c */ 

Idefine INCLJ50SPROCESS 
Idefine INCL DOSSIGNALS 
Idefine INCLJOSERRORS 

linclude <os2.h> 

Idefine SLEEPTIME 50L 

Idefine TIMEOUT 5000L 


VOID API ENTRY CtrIC Hand1er(argl, arg2) /** Define signal handler **/ 
USKORT argl; 

USHORT arg2; 

{ 

printf (“Handler for Ctrl-C now running. \n") ; 
return; 

} 

mainQ 

{ 

ULONG RamSem ■ OL; /* Allocate and initialize Ram Semaphore */ 

ULONG far *RamSemHandle 3 &RamSem; /* Ram Semaphore handle */ 

USHORT rc; 

/* Establish signal handler ie/ 

i f ( 1 (rc a DosSetSi gHandl er ( (PFNS I CHANDLER) CtrlC_Handler, 

NULL, /ie Previous handler - ignored ie/ 

NULL, /ie Previous action - ignored ie/ 

SIGA_ACCEPT, /* Request type ie/ 

SIG_CTRLC) ) ) /ie Signal number ie/ 

printf ("Process2 has set Ctrl-C handler. \n"); 
else 

/ie Error processing on rc ie/; 

/ie Get semaphore for first time ie/ 

if(! (rc=DosSemRequest(RamSemHandle, /ie Semaphore handle ie/ 

TIMEOUT))) /ie Timeout interval ie/ 

pri ntf ( "Semaphore obtai ned . \n" ) ; 

/ ieieie Disable and then enable signal -handling ieieie/ 

if (! (rc a DosHoldSignal (HLDSIG DISABLE))) /ieie Action code - disable ieie/ 

{ 

pri ntf ( “Si gnal 1 i ng DISABLED . \n" ) ; 

/ie Do si gnal -proof work here ie/ 

if (! (rc=DosHoldSignal (HLDSIG ENABLE))) /ieie Action code - enable ieie/ 
pri ntf ( "Si gnal 1 i ng ENABLED. \n" ) ; 

} 

/ie At this point, process 1 may have sent a Ctrl-C signal, ie/ 

/ie Try to obtain semaphore again — resulting in Timeout, ie/ 

/ie The Timeout, however, may be interrupted by the signal. */ 

printf("Process2 will now wait on a Ramsem for a while.\n"); 
if((rc=DosSemRequest(RamSemHandle. /ie Semaphore handle ie/ 

TIMEOUT)) /ie Timeout interval ie/ 

== ERRORJNTERRUPT) 

printf(“Process2 interrupted while waiting, rc is %d.\n", rc); 

} 
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FAPI DosInsMessage - 

Insert Variable Text Strings In Message 


This call inserts variable text string information into the body of a message. This is useful when mes- 
sages are loaded before insertion text strings are known. 


DosInsMessage (IvTable, IvCount, Msginput, MsglnLength, DataArea, DataLength,MsgLength) 


Parameters 

IvTable (PCHAR FAR *) - input 

List of double-word pointers. Each pointer points to an ASCIIZ or null terminated DBCS string 
(variable insertion text). 0 to 9 strings can be present. 

IvCount (USHORT) - input 

0 — 9 is the count of variable insertion text strings. If IvCount is 0, IvTable is ignored. 

Msglnput (PSZ) - input 

Address of the input message. 

MsglnLength ( USHORT) - input 

Length, in bytes, of the input message. 

DataArea (PCHAR) - output 

Address of the user storage that returns the updated message. If the message is too long to fit in the 
caller's buffer, as much of the message text as possible is returned with the appropriate return code. 

DataLength ( USHORT) - input 

Length, in bytes, of the user's storage area. 

MsgLength (PUSHORT) - output 

Address of the length, in bytes, of the updated message. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

316 ERROR_MR_MSG_TOO_LONG 

320 E R ROR_M R_i N V _l VCOU NT 

Remarks 

DosInsMessage returns an error indicating that IvCount is out of range when IvCount is greater than 9. A 
default message is also placed in the caller's buffer. Refer to “DosGetMessage — Retrieve System 
Message with Variable Text" on page 2-143 for details on the default messages. If the numeric value of x 
in the %x sequence for %1through%9 is less than or equal to IvCount, then text insertion, by substitution 
for %x, Is performed for all occurrences of %x in the body of the message. Otherwise text insertion is 
ignored and the %x sequence is returned unchanged in the message. Text insertion is performed for ali 
text strings defined by IvCount and IvTable. 

Variable data insertion does not depend on a blank character delimiter nor are blanks automatically 
inserted. 


Chapter 2. Control Program Function Calls 


2-169 




DosInsMessage - 

Insert Variable Text Strings In Message 


FAPI 


C Language 

Idefine INCLJJOSMISC 

USHORT rc a DosInsMessage(IvTable, IvCount, Msglnput, MsglnLength, 

DataArea, DataLength, MsgLength); 


PCHAR FAR * 

IvTable; 

/* Table of variables to insert */ 

USHORT 

IvCount; 

/* Number of variables */ 

PSZ 

Msglnput; 

/* Address of input message */ 

USHORT 

MsglnLength; 

; /* Length of input message */ 

PCHAR 

DataArea; 

/* Updated message (returned) */ 

USHORT 

DataLength; 

/* Length of updated message buffer */ 

PUSHORT 

MsgLength; 

/* Length of updated message (returned) */ 

USHORT 

rc; 

/* return code */ 

Assembler Language 

EXTRN DosInsMessage: FAR 


INCLJJOSMISC 

EQU 1 


PUSH® OTHER 

IvTable 

;Table of variables to insert 

PUSH WORD 

IvCount 

; Number of variables 

PUSH® ASCI IZ 

Msglnput 

; Input message string 

PUSH WORD 

MsglnLength 

; Length of input message 

PUSH® OTHER 

DataArea 

•.Updated message (returned) 

PUSH WORD 

DataLength 

; Length of updated message buffer 

PUSH® WORD 

MsgLength 

; Length of updated message (returned) 

CALL DosInsMessage 


Returns WORD 
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DosKIIIProcess - 
Terminate Process 


This call flags a process to terminate and returns the termination code to its parent. 


DosKIIIProcess (ActlonCode, ProcessID) 


Parameters 

ActlonCode (USHORT) - input 

The processes to be flagged for termination. 

Value Definition 

0 A process and all its descendant processes. The process must be either the current 

process or a child process created by the current process. (Detached processes cannot 
be flagged for termination.) After the indicated process terminates, its descendants are 
flagged for termination. 

t Any process. Only the indicated process is flagged for termination. 

ProcessID (P/D) - input 

Process ID of the process, or root process of the process tree to be flagged for termination. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

13 ERRORJNVALID_DATA 

303 ERROR_INVALID_PROCID 

305 ERROR_NOT_DESCENDANT 

Remarks 

DosKillProcess allows a process to send the termination signal SIGTERM to another process or group of 
processes. The default action of the system is to terminate each of the processes. A process can inter- 
cept this action by installing a signal handler for SIGTERM with DosSetSigHandler. This gives the 
process the opportunity to clean up its files before it terminates with DosExit. 

If there is no signal handler, the effect on the process is the same as if one of its threads had issued 
DosExit for the entire process. All file buffers are flushed and the handles opened by the process are 
closed. However, any internal buffers managed by programs external to OS/2 are not flushed. An 
example of such a buffer could be a C language library’s internal character buffer. 

If a parent process is waiting for a child process to end because of a DosCwait request, and the child is 
sent the SIGTERM signal but does not have a SIGTERM signal handler installed, the DosCwait request 
returns the “un intercepted DosKillProcess” termination code. 


C Language 

idefine INCL_DOSPROCESS 

USHORT rc ■ DosKi 11 Process ( Act ionCode, ProcessID); 


USHORT 

PID 

Act ionCode; 
ProcessID; 

/* 

/* 

Indicate to flag 
ID of process or 

descendant processes 
root of process tree 

*/ 

*/ 

USHORT 

rc; 

/* 

return code */ 




Chapter 2. Control Program Function Calls 


2-171 






DosKillProcess - 
Terminate Process 


Assembler Language 

EXTRN DosKillProcess: FAR 
INCL_DOSPROCESS EQU 1 

PUSH WORD ActionCode ; Indicator for child process termination 

PUSH WORD Process ID ;ID of the process being terminated 

CALL DosKillProcess 

Returns WORD 

Example 

The following example demonstrates how to create a process, obtain process ID information, and kill a 
process. Processl invokes process2 to run asynchronously. It obtains and prints some PID information, 
and then kills process2. 
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DosKillProcess - 
Terminate Process 


/* processl.c */ 

Idefine INCL_DOSPROCESS 
linclude <os2.h> 


#define START_PROGRAM "process2.exe" /* Program pointer */ 


iin() 

CHAR 

Obj Fail [50]; 

/* Object name buffer */ 

RESULTCODES 

ReturnCodes; 

/* 

PIDINFO 

Pidlnfo; 


PID 

Parent ID; 

/* 

USHORT 

rc; 



printf ("Processl now running. \n“); 

/** Start a child process. **/ 
if (! (DosExecPgm(ObjFai 1 , 

sizeof (Obj Fail) , 

EXEC_ASYNC, 

NULL, 

NULL, 

&ReturnCodes, 

START_PROGRAM) ) ) 
printf ("Process2 started. \n“); 

/** Obtain Process ID information and print it **/ 
i f ( ! (rc=»DosGetPID(&PidInfo> ) ) /* Process ID's (returned) */ 

printf ("DosGetPID: current process ID is %d; thread ID is %d; parent process ID is %d.\n‘\ 
Pidlnfo.pid, Pidlnfo.tid, Pidlnfo.pidParent); 
i f ( ! ( rc=DosGet PP I D ( 

ReturnCodes.codeTerminate, /* Process whose parent is wanted */ 

&ParentID))) /* Address to put parents PID */ 

printf (“Child process ID is %d; Parent process ID is %d.\n". 

Ret urnCodes . codeTermi nate , Parent ID) ; 

/** Terminate process2 **/ 

if(l(rc«DosKi11Process(DKPJ > R0CESSTREE, /* Action code - kill process and descendants */ 
ReturnCodes.codeTerminate))) /* PID of root of process tree */ 
print f("Process2 terminated by processl. \n“); 

} 


/* process2.c */ 

Idefine INCL_DOSPROCESS 

#indude <os2.h> 

#define SLEEPTIME 500L 
Idefine RETURN JODE 0 

main() 

{ 

printf("Process2 now running.\n“); 

/* Sleep to allow processl to kill it */ 
DosSleep(SLEEPTIME) ; /* Sleep interval */ 

Dos Exi t ( EXI T_PR0CESS , /* Action Code */ 

RETURN CODE); /* Result Code */ 

} 


/* Object name buffer */ 

/* Length of obj. name buffer */ 

/* Execution flag - asynchronous */ 

/* No args. to pass to proce$s2*/ 

/* Process2 inherits processl' s environment */ 
/* Ptr. to resultcodes struct. */ 

/* Name of program file */ 
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DosLoadModule - 
Load Dynamic Link Module 


This call loads a dynamic link module and returns a handle for the module. 


DosLoadModule (ObiNameBuf, ObjNameBufL, ModuleName, ModuleHandle) 


Parameters 

ObiNameBuf (PSZ) — output 

Address of the name of an object that contributed to the failure of DosLoadModule. 

ObjNameBufL ( USHORT) - input 

Length, in bytes, of the buffer described by ObjNameBuf. 

ModuleName (PSZ) - input 

Address of the ASCIIZ name string containing the dynamic link module name or the pathname string. 
The filename extension used for dynamic link libraries is .DLL. When a pathname is provided, the 
module name may have any extension. The internal module name (the name given in the LIBRARY 
statement in the .DEF file) must be the same as the filename without the extension. 

ModuleHandle (PH MODULE) - output 

Address of the handle for the dynamic link module. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOT_FOUND 

3 ERROR_PATHJSIOT_FOUND 

4 ERROR_TOO_MANY_OPEN_FILES 

5 ERROR_ACCESS_DENIED 

8 ERROR_NOT_ENOUGH_MEMORY 

11 ERROR_BAD_FORMAT 

26 E R ROR_NOT_DOS_DISK 

32 ERROR_SHARING_VIOLATION 

33 ERROR_LOCK_VIOLATION 

36 ERROR_SHARING BUFFER_EXCEEDED 

95 ERRORJNTERRUPT 

108 ERROR_DRIVE_LOCKED 

123 ERRORJNVALIDJMAME 

127 ERROR_PROC_NOT_FOUND 

180 ERROR_INVALID_SEGMENT_NUMBER 

182 ERRORJNVALIDJDRDINAL 

190 ERRORJNVALID~MODULETYPE 

191 ERRORJNVALID_EXE_SIGNATURE 

192 ERROR_EXE_MARKED_INVALID 

194 ERROR JTERATED_DATA^EXCEEDS_64k 

195 ERRORJNVALID_MINALLOCSIZE 

196 ERROR_DYNLINK - FROM_INVALID_RING 

198 ERRORJNVALID_SEGDPL 

199 ERROR_AUTODATASEG_EXCEEDS_64k 

201 ERROR_RELOC_CHAIN_XEEDS_SEGLIM 

206 ERROR_FILENAME_EXCED_RANGE 
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DosLoadModule - 
Load Dynamic Link Module 


Remarks 

If the file is an OS/2 dynamic link module, it is loaded, and a handle is returned. This handle is used for 
freeing the dynamic link module with a DosFreeModule request, getting procedure addresses with 
DosGetProcAddr requests, and getting the fully qualified file name with a DosGetModName request. 

DosLoadModule may not be called from a dynamic library initialization routine if the module to be loaded 
or any module referenced by it contains a dynamic link library initialization routing. 

C Language 

Idefine INCL_DOSMODULEMGR 

USHORT rc = DosLoadModule (ObjNameBuf , ObjNameBufL, ModuleName, ModuleHandle) ; 

PSZ ObjNameBuf; /* Address of object name buffer */ 

USHORT ObjNameBufL; /* Length of object name buffer */ 

PSZ ModuleName; /* Address of module name string */ 

PKMODULE ModuleHandle; /* Address of module handle (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosLoadModule: FAR 
INCLJ30SM0DULEMGR EQU 1 

PUSH? OTHER ObjNameBuf ;0bject name buffer (returned) 

PUSH WORD ObjNameBufL ; Length of object name buffer 

PUSH? ASCI IZ ModuleName ;Module name string 

PUSH? WORD ModuleHandle ;Module handle (returned) 

CALL DosLoadModule 

Returns WORD 

Example 

This example loads a module. 

#define INCL_DOSMODULEMGR 

Idefine MODULE_NAME "abed" 

Idefine FULL_MODULE_NAME '*\\nifty\\abcd.dl 1 11 

CHAR LoadError[10O]; 

HMODULE ModuleHandle; 

USHORT rc; 

if (DosLoadModule(LoadError, /* Object name buffer */ 

sizeof (LoadError), /* Length of object name buffer */ 

MODULE_NAME, /* Module name string */ 

&ModuleHandle) -= 2) /* Module handle */ 
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DosLockSeg - 

Lock Segment in Memory 


This call locks a discardable segment in memory. 


DosLockSeg (Selector) 


Parameters 

Selector ( SEL ) - input 

Selector of the segment to be locked. 

rc {USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

5 ERROR_ACCESS_DENIED 

157 ERROR_DISCARDED 

Remarks 

Discardable segments are useful for holding objects that are accessed for short periods of time and that 
can be regenerated quickly if discarded. Examples are cache buffers for a data base package, saved 
bitmap images for obscured windows or precomputed display images for a word processing application. 

Discardable memory is allocated by a call to DosAllocSeg or DosAllocHuge with AllocFlags bit 2 set. 
Upon allocation, the memory is automatically locked for access by the allocating process and cannot be 
discarded. After the segment is unlocked by a DosUnlockSeg request, the memory can be discarded by 
the memory manager to remedy a low memory situation. Once memory is discarded, a DosLockSeg call 
returns ERROR_DISCARDED. The memory is reallocated by a call to DosReallocSeg or DosReallocHuge. 
The reallocation request automatically locks the memory. 

Memory allocated as discardable by a DosAllocSeg or DosAllocHuge request may also have been desig- 
nated as shareable. Sharing processes that access the discardable shared memory with DosGetSeg 
have to lock the memory by calling DosLockSeg. See DosGetSeg for more information. 

DosLockSeg and DosUnlockSeg calls may be nested. If DosLockSeg is called multiple times to lock a 
segment, the same number of calls must be made to DosUnlockSeg before the segment is unlocked. 
However, if a segment is locked 255 times, it becomes permanently locked. Additional calls to 
DosLockSeg and DosUnlockSeg have no effect on the segment's locked state. 

This function is used on segments that have been allocated through DosAllocSeg with AllocFlags bit 2 
(0100B) set. It may be also used on segments that are non-discardable, in which case it has no effect. 

C Language 

#de fine INCLJ30SMEMMGR 

USHORT rc = DosLockSeg(Selector) ; 

SEL Selector; /* Selector to lock */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosLockSeg: FAR 
INCL_DO$MEMMGR EQU 1 

PUSH WORD Selector ; Selector to lock 
CALL DosLockSeg 

Returns WORD 
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DosMakeNmPipe — 
Create Named Pipe 


This call creates the specified named pipe and returns its handle. 

DosMakeNmPipe (PipeName, PipeHandle, OpenMode, PipeMode, OutBufSize, InBufSize, 

TimeOut) 

Parameters 

PipeName (PSZ) - input 

Address of the ASCIIZ name of the pipe to be opened. Pipes are named \PIPE\PipeName. 

PipeHandle ( PHPIPE ) - output 

Address of the handle of the named pipe that is created. 

OpenMode ( USHORT) - input 

The OpenMode parameter contains the following bit fields: 

Bit Description 

15 Reserved and must be zero. 

14 Write-Through flag: The file is opened as follows: 

0 = Write-behind to remote pipes is allowed. 

1 = Write-behind to remote pipes is not allowed. 

Setting the Write-Through flag is meaningful only for a remote pipe. Occasionally, data 
written to a remote pipe is buffered locally and then sent across the network to the pipe 
at a later time. Setting the Write-Through bit ensures that data is sent to the remote pipe 
as soon as it is written. 

13-8 Reserved and must be zero. 

7 Inheritance flag: The file handle is as follows: 

0 = Pipe handle is inherited by a spawned process resulting from a DosExecPgm call. 

1 = pjpe handle is private to the current process and cannot be inherited. 

6-2 Reserved and must be zero. 

1-0 Access field: The pipe access is assigned as follows: 

00 = In-bound pipe (client to server) 

01 = Out-bound pipe (server to client) 

10 = Duplex pipe (server to/from client) 

Any other value is invalid. 

PipeMode ( USHORT) - input 

The PipeMode parameter contains the following bit fields: 

Bit Description 

15 Blocking flag: The pipe is defined as follows: 

0 = Reads/Writes block if no data available. 

1 = Reads/Writes return immediately if no data available. 

Reads normally block until at least partial data can be returned. Writes by default block 
until all bytes requested have been written. Non-blocking mode (1) changes this 
behavior as follows: 

• DosRead returns immediately with error NO_DATA if no data is available. 
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Create Named Pipe 


• DosWrite returns immediately with BytesWritten = 0 if insufficient buffer space is 
available in the pipe or the entire data area is transferred. 

14-11 Reserved and must be zero. 

10 Type of named pipe: The pipe is defined as follows: 

0 = Pipe is a byte stream pipe. 

1 = Pipe is a message stream pipe. 

All writes to message stream pipes record the length of the write along with the written 
data (see DosWrite). The first two bytes of each message represents the length of that 
message and is called the message header. A header of all zeros is reserved. Zero 
length messages are not allowed (OS/2 no-ops zero-length I/Os). 

9 Reserved and must be zero. 

8 Read mode: The pipe is defined as follows: 

0 = Read pipe as a byte stream. 

1 = Read pipe as a message stream. 

Message pipes can be read as byte or message streams, depending on this bit. Byte 
pipes can only be read as byte streams (see DosRead) 

7-0 ICount field (Instance count): Byte wide (8-bit) count to control pipe instances. When 

making the first instance of a named pipe, ICount specifies how many instances can be 
created. Instances are as follows: 

Value Definition 

1 This can be the only instance (pipe is unique). 

1 < value < 255 The number of instances is limited to the value specified. 

-1 The number of instances is unlimited. 

0 Reserved value. 

Subsequent attempts to make a pipe fails if the maximum number of allowed instances 
already exists. The ICount parameter is ignored when making any other than the first 
instance of a pipe. When multiple instances are allowed, multiple clients can simultane- 
ously issue DosOpen to the same pipe name and get handles to distinct pipe instances. 

OutBufSIze (USHORT) - input 

An advisory to the system of the number of bytes to allocate for the outgoing buffer. 

InBufSIze ( USHORT) - input 

An advisory to the system of the number of bytes to allocate for the incoming buffer. 

TlmeOut ( ULONG ) - input 

Default value for the TimeOut parameter to DosWaitNmPipe. This value may be set only at the cre- 
ation of the first instance of the pipe name. If the value is zero, a system wide default value (50 ms) 
is chosen. 

rc ( USHORT) - return 


Return code descriptions are: 

0 

NO_ERROR 

3 

E R ROR_PATH_NOT_FOU N D 

8 

ERROR J40tJn0UGHJV1EM0RY 

84 

ER ROR_OUT_OF_ST R UCTU RES 

87 

ERROR_INVALID_PARAMETER 

231 

ERROR_PIPE BUSY 
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Create Named Pipe 


Remarks 

A named pipe provides two-way communication between a server process and a number of client proc- 
esses. In addition, the named pipe can have multiple instances created by multiple server processes. 

The server creates the pipe with DosMakeNmPipe. The ICount parameter is significant only for the first 
instance created of the named pipe. The ASCiiZ name string specified for the named pipe must include 
the prefix \PIPEV 

After creating the named pipe, the server issues DosConnectNmPipe to wait for a client to open the pipe 
with DosOpen. If all instances of a named pipe are busy, a client process can issue DosWaitNmPipe and 
wait for an instance to become available before it reissues DosOpen. A client can determine whether the 
pipe is ready to accept a DosOpen by issuing DosPeekNmPipe to return the pipe's state. 

Server and client processes communicate by issuing DosRead, DosReadAsync, DosWrite, and 
DosWriteAsync calls. DosBufReset can be used to to synchronize read and write dialogs. A server 
process that need to support a large number of clients for a local named pipe can coordinate access to 
the pipe with DosSetNmPipeSem and DosQNmPipeSemState calls. 

Server and client processes can also communicate by means of transaction and procedure calls. 
DosTransactNmPipe and DosCalINmPipe are supported only for duplex message pipes. 

Issuing DosClose ends the client’s access to the named pipe. To prepare the pipe for its next client, the 
server process issues DosDisConnectNmPipe followed by DosConnectNmPipe. 

When all handles to one end of the pipe are closed, the pipe is considered broken. If the pipe is broken 
and the server issues DosCiose, the pipe is immediately deallocated. 


C Language 

Ideflne INCl_DOSNMPIPES 

USHORT re = DosMakeNmPipe (Pi peName, PipeHandle, OpenMode, PipeMode, 

OutBufSize, InBufSize, TimeOut); 


PSZ 


Pi peName; 

/* 

Pipe name */ 

PHPIPE 


PipeHandle; 

/* 

Pipe handle (returned) */ 

USHORT 


OpenMode; 

/* 

DOS open mode of pipe */ 

USHORT 


Pi peMode; 

/* 

Pipe open mode */ 

USHORT 


QutBufSize; 

/* 

Advisory outgoing buffer size 

USHORT 


InBufSize; 

/* 

Advisory incoming buffer size 

ULONG 


TimeOut; 

!* 

Timeout for DosWaitNmPipe */ 

USHORT 


rc; 

/* 

return code */ 

Assembler Language 


EXTRN 

DosMakeNmPi pe:FAR 



INCL.DOSNMPIPES EQU 1 



PUSH@ 

ASCIIZ 

Pi peName 

;Pipe 

name 

PUSH® 

WORD 

PipeHandle 

; Pi pe handle (returned) 

PUSH 

WORD 

OpenMode 

;D0S open mode of pipe 

PUSH 

WORD 

PipeMode 

; Pi pe open mode 

PUSH 

WORD 

OutBufSize 

; Advisory outgoing buffer size 

PUSH 

WORD 

InBufSize 

; Advisory incoming buffer size 

PUSH 

DWORD 

TimeOut 

;Timeout for DosWaitNmPipe 

CALL 

DosMakeNmPipe 



Returns WORD 
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DosMakePipe - 
Create Pipe 


This call creates a pipe. 


DosMakePipe (ReadHandle, WrlteHandle, PipeSize) 


Parameters 

ReadHandle ( PHFILE ) - output 

Address of the read handle of the pipe. 

WrlteHandle (PHFILE) - output 

Address of the write handle of the pipe. 

PipeSize ( USHORT) - input 

Storage size, in bytes, to reserve for the pipe. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

4 ERROR_TOO_MANY_OPEN_FILES 

8 ERROR JvlOTJENOUGH_MEMORY 

109 ERROR_BROKEN_PIPE 


Remarks 

Pipes are mechanisms used within a closely related group of processes. There are no control, permis- 
sion mechanisms, or checks performed on operations to pipes. 

When there is insufficient space in a pipe for the data being written, a requesting thread blocks until 
enough data is removed to allow the write request to be satisfied. If the PipeSize parameter is 0, then the 
pipe is created with a default size of 512 bytes. 

When all users close the handles, a pipe is deleted. If two processes are communicating by a pipe and 
the process reading the pipe ends, the next write gets the "ERROR^BROKEhmPE" error code. 


C Language 

^define INCLJOSQUEUES 

USHORT rc = DosMakePipe (ReadHandle, WriteHandle, PipeSize); 


PHFILE 

ReadHandle; 

/* Address to put read handle (returned) */ 

PHFILE 

WriteHandle; 

/* Address to put write handle (returned) */ 

USHORT 

PipeSize; 

/* Size to reserve for the pipe */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosMakePipe; FAR 
1NCL_D0$QUEUES EQU 1 


PUSHG 

WORD 

ReadHandle 

PUSH@ 

WORD 

WriteHandle 

PUSH 

WORD 

PipeSize 

CALL 

DosMakePipe 


;Read handle (returned) 

;Write handle (returned) 

;$ize to reserve for the pipe 


Returns WORD 
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DosMemAvail - 

Get Size of Largest Free Memory Block 


This call returns the size of the largest block of free memory. 


DosMemAvail (MemAvailSize) 


Parameters 

MemAvailSize ( PULONG ) - output 

Address of the size of the largest free block of memory. 

rc (USHORT) - return 

Return code description is: 

0 NO_ERROR 

Remarks 

DosMemAvail allows an application to determine how heavily used system memory is at a particular 
time. The returned value is a “snapshot 1 ' that may be valid only at the moment this function is issued and 
can be expected to change at any time due to system activity. 

This call can be used as an indicator for memory availability before a call to DosAIIocHuge is made. 

C Language 

#define INCL_D0SMEMMGR 

USHORT rc B DosMemAvai 1 (MemAvai 1 Si ze) ; 

PULONG MemAvailSize; /* Size available (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosMemAvail: FAR 
INCL_D0SMEMMGR EQU 1 

PUSH® DWORD MemAvailSize ;Size available (returned) 

CALL DosMemAvai 1 

Returns WORD 
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DosMkDir - 
Make Subdirectory 


FAPI 


This call creates a subdirectory. 


DosMkDir (DirName, Reserved) 


Parameters 

DErName (PSZ) - input 

Address of the ASCIIZ directory path name, which may or may not include a drive specification. If no 
drive is specified, the current drive is assumed. 

DosQSysInfo is called by an application during initialization to determine the maximum path length 
allowed by OS/2. 

Reserved ( ULONG ) - input 

Reserved and must be set to zero. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

3 ER RORP ATHNOTFOU N D 

5 ERROR_ACCESS_DENIED 

26 ERROR_NOT_DOS_DISK 

87 ERROR JNVALID_PARAMETER 

108 ERROR_DRIVE_LOCKED 

206 ERROR_FILENAME_EXCED_RANGE 

Remarks 

If any subdirectory names in the path do not exist, the subdirectory is not created. Upon return, a subdi- 
rectory is created at the end of the specified path. 

DosQSysInfo must be used by an application to determine the maximum path length supported by OS/2. 
The returned value should be used to dynamically allocate buffers that are to be used to store paths. 

If a program running with the NEWFILES bit set tries to create a directory with blanks immediately pre- 
ceding the dot on a FAT drive, the system rejects the name. For example, if c: is a FAT drive, the name 
“file .txt” is rejected and the name “file.txt” is accepted. 


C Language 

Idefine INCL_DOSFILEMGR 

USHORT rc s DosMkDir (DirName, Reserved); 


PSZ 

DirName; 

/* New directory string name */ 

ULONG 

0; 

/* Reserved (must be zero) */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosMkDir: FAR 
INCL_DOSFI LEMGR EQU 1 

PUSH0 ASCIIZ DirName ;New directory name string 

PUSH DWORD 0 Reserved (must be zero) 

CALL DosMkDir 

Returns WORD 
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FAPI DosMkDir2 - 

Make Subdirectory and Define Extended Attributes 


This call creates a subdirectory that has extended attributes associated with it. 


DosMkDlr2 (DirName, EABuf, Reserved) 


Parameters 

DirName (PSZ) - input 

Address of the ASCIIZ directory path name, which may or may not contain a drive specification. If no 
drive is specified, the current drive is assumed. 

DosQSysInfo is cailed by an application during initialization to determine the maximum path length 
allowed by OS/2. 

EABuf (PEAOP) - input/output 

Address of the extended attribute buffer, which contains an EAOP structure. An EAOP structure has 
the following format: 

fpGEALIsl (PGEALIST) 

Address of GEAList. GEAList is a packed array of variable length “get EA” structures, each con- 
taining an EA name and the length of the name. 

fpFEALIst (PFEALIST) 

Address of FEAList. FEAList is a packed array of variable length “full EA" structures, each con- 
taining an EA name and its corresponding value, as well as the lengths of the name and the 
value. 

oError (ULONG) 

Offset into structure where error has occurred. 

On input, the fpGEAList field and oError fields are ignored. The EA setting operation is performed on 
the information contained in FEAList. If extended attributes are not to be defined or modified, then 
EABuf must be set to null. Following is the FEAList format: 

cbList (ULONG) 

Length of the FEA list, including the length itself, 
list (FEA) 

List of FEA structures. An FEA structure has the following format: 

Flags (BYTE) 

Bit indicator describing the characteristics of the EA being defined. 

Bit Description 

15 Critical EA. 

14-0 Reserved and must be set to zero. 

if bit 15 is set to 1 , this indicates a critical EA. If bit 15 is 0, this means the EA is noncritical; 
that Is, the EA is not essential to the intended use by an application of the file with which it is 
associated. 

cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character. 
cbValue (USHORT) 

Length of EA value, which cannot exceed 64KB. 
szName (PSZ) 

Address of the ASCIIZ name of EA. 
aValue (PSZ) 

Address of the free-format value of EA. 

Note: The szName and aValue fields are not included as part of header or include files. 

Because of their variable lengths, these entries must be built manually. 
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DosMkDir2 - 

Make Subdirectory and Define Extended Attributes 


FAPI 


On output, fpGEAList is unchanged. fpFEAList is unchanged as is the area pointed to by fpFEAList. If 
an error occurred during the set, oError is the offset of the FEA where the error occurred. The API 
return code is the error code corresponding to the condition generating the error, if no error 
occurred, oError is undefined. 

If EABuf is 0x00000000, then no extended attributes are defined for the directory. 

Reserved ( ULONG ) - input 

Reserved and must be set to zero. 

re (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

3 ERROR_PATH_NOT_FOUND 

5 ERROR_ACCESS_DENIED 

26 ER ROR_NOT_DOS_DlSK 

87 ERRORJNVALID_PARAMETER 

108 ERROR__DRIVEJ_OCKED 

206 ERROR_FILENAME_EXCED_RANGE 

254 ERROR_INVALID_EA_NAME 

255 ERROR_EA_LISTJNCONSISTENT 

Remarks 

DosMkDir2 allows an application to define extended attributes for a subdirectory at the time of its cre- 
ation. 

If any subdirectory names in the path do not exist, the subdirectory is not created. Upon return, a subdi- 
rectory is created at the end of the specified path. 

DosQSysinfo must be used by an application to determine the maximum path length supported by OS/2. 
The returned value should be used to dynamically allocate buffers that are to be used to store paths. 

If a program running with the NEWFILES bit set tries to create a directory with blanks immediately pre- 
ceding the dot on a FAT drive, the system rejects the name. For example, if c: is a FAT drive, the name 
“file .txt” is rejected and the name "file.txt" is accepted. 
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FAPI DosMkDir2 - 

Make Subdirectory and Define Extended Attributes 

C Language 

typedef struct _6EA { /* gea */ 

BYTE cbName; /* name length not including NULL */ 

CHAR szName[l]; /* attribute name */ 

} GEA; 

typedef struct _GEALIST { /* geal */ 

ULONG cbList; /* total bytes of structure including full list */ 

GEA 1 1st [1] ; /* variable length GEA structures */ 

} GEALIST; 

typedef struct _FEA { /* fea */ 

BYTE fEA; /* flags */ 

BYTE cbName; /* name length not including NULL */ 

USHORT cbValue; /* value length ie/ 

} FEA; 

typedef struct _FEALIST { fie feal */ 

ULONG cbList; /ie total bytes of structure including full list */ 

FEA list [1] ; /ie variable length FEA structures ie/ 

} FEAL I ST; 

typedef struct _EA0P { /ie eaop */ 

PGEALIST fpGEAList; /ie general EA list ie/ 

PFEALIST fpFEALi St; /ie full EA list ie/ 

ULONG oError; 

} EAOP; 

#define INCLJJOSFILEMGR 

USHORT rc = DosMkDir2(DirName, EABuf , Reserved); 


PSZ 

DirName; 

/ie New directory name string ie/ 

PEAOP 

EABuf; 

/ie Extended attribute buffer */ 

ULONG 

0; 

/ie Reserved (must be zero) ie/ 

USHORT 

rc; 

/ie return code ie/ 
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DosMkDir2 - 

Make Subdirectory and Define Extended Attributes 


FAPI 


Assembler Language 

GEA struc 

gea_cbName db ? ;name length not including NULL 

gea_szNarne db 1 dup (?) ; attribute name 

GEA ends 

GEALIST struc 

geal_cbList dd ? ; total bytes of structure including full list 

geal_list db size GEA * 1 dup (?) ; variable length GEA structures 

GEALIST ends 

FEA struc 

fea_fEA db ? ;flags 

fea_cbName db ? ;name length not including NULL 
fea_cbValue dw ? ; value length 

FEA ends 

FEALIST struc 

feal_cbLi st dd ? ;total bytes of structure including full list 

f eal_l i st db size FEA * 1 dup (?) ; variable length FEA structures 

FEALIST ends 

EAOP struc 

eaop_fpGEAList dd ? ;general EA list 

eaop_fpFEAList dd ? ;full EA list 

eaop_oError dd ? ; 

EAOP ends 

EXTRN DosMkDi r2:FAR 
INCL_DOSFILEMGR EQU 1 

PUSH® ASCI IZ DirName ;New directory name string 

PUSH® OTHER EABuf ; Extended attribute buffer 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosMkDi r2 

Returns WORD 
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xpm DosMonClose - 

Close Connection to Device Monitor 


This call terminates character device monitoring. All monitor buffers associated with this process are 
flushed and closed. 


DosMonClose (Handle) 


Parameters 

Handle ( HMONITOR ) - input 

Device handle returned from a previous DosMonOpen call. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

381 ERROR_MON_INVALID_HANDLE 

Remarks 

A single process may register one or more monitors with a character device using the same device 
handle returned from a previous DosMonOpen call. When DosMonClose is issued for a specific, opened 
device handle, all monitors for the current process registered with this handle terminate. 

When DosMonClose is issued, the monitor loses access to the device data stream. Before issuing 
DosMonClose, monitor threads calling DosMonRead and DosMonWrite should be terminated. After 
DosMonClose has been called: 

• DosMonRead calls return an ERROR_MON_BUFFERJEMPTY return code. 

• DosMonWrite calls return an ERROR_NOT_ENOUGH_MEMORY return code. 

Data segments containing monitor buffers should not be freed until after DosMonClose is called. If data 
segments containing monitor buffers are freed before DosMonClose is called, a GP fault occurs when 
DosMonClose is called and the process is terminated. 

For a detailed description of this call see the chapter “Character Device Monitors” in the IBM Operating 
System/2 Version 1.2 HO Subsystems And Device Support Volume 1 . 


C Language 

#define INCL_D0SK0NIT0RS 
USHORT rc - DosMonClose (Handle) ; 


HMONITOR 

Handle; 

/* Monitor handle */ 

USHORT 

rc; 

/it return code it/ 


Assembler Language 

EXTRN DosMonClose: FAR 
INCUJOSMONITORS EQU 1 

PUSH WORD Handle ; Monitor handle 

CALL DosMonClose 

Returns WORD 
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DosMonOpen - 

Open Connection to Device Monitor 


xPM 


This call gains access to a character device data stream. 


DosMonOpen (Devname, Handle) 


Parameters 

Devname (PSZ) - input 

Address of the device name string. 

Handle (PHMONITOR) - output 

Address of the handle for the monitor. This value must be passed to DosMonReg to communicate 
with the device, and is passed to DosMonClose to close the connection to the monitor. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

110 ERROR_OPENFAILED 

379 ERROR_MONJNVALID_PARMS 

380 ERROR_MONJNVALID_DEVNAME 

Remarks 

For a detailed description of this call see the chapter “Character Device Monitors” in the IBM Operating 
System 12 Version 1.2 I/O Subsystems And Device Support Volume 1. 

Only one DosMonOpen call is necessary per device per process. That is, several DosMonReg calls can 
be made using the same monitor handle to the same device. This allows monitors to be registered using 
different values for Index from the same process and going to the same device. When the DosMonClose 
is issued, ail of the monitors registered on the handle is closed. 

C Language 

#define INCL_D0SH0NIT0RS 

USHORT rc = DosMonOpen (Devname, Handle); 

PSZ Devname; /* Device name string */ 

PHMONITOR Handle; /* Monitor handle (returned) * 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosMonOpen: FAR 
INCL_DOSMONITQRS EQU 1 

PUSH? ASCI IZ Devname ; Device name string 

PUSH? WORD Handle ;Monitor handle (returned) 

CALL DosMonOpen 

Returns WORD 
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xpm DosMonRead - 

Read Input from Monitor Structure 


This call waits for and moves a data record from the input buffer of a registered character device monitor 
and places it in a private data area where the monitor can freely access it. 


DosMonRead (Bufferl, WaltFlag, DataBuffer, Bytecnt) 


Parameters 

Bufferl {PBYTE) - input 

Address of the monitor input buffer. 

WaltFlag (UCHAR) - input 
Valid values are: 

Value Definition 

0 The monitor thread that issues DosMonRead wishes to block until a data record is avail- 
able in its input buffer. 

1 The monitor thread that issues DosMonRead does not wish to block when its input buffer 
is empty. 

DataBuffer (PBYTE) - input 

Address of the buffer in the calling process address space that the data from the monitor’s input 
buffer is read into. The length of DataBuffer must be the entry value of Bytecnt. 

Bytecnt (PUSHORT) - input/output 

Address of the length of DataBuffer, on entry to DosMonRead. On the return from DosMonRead, 
Bytecnt specifies the number of bytes of data moved. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

379 ERROR_MONJNVALID_PARMS 

382 ERROR_MON_BUFFER_TOO_SMALL 

383 ERROR_MONJ3UFFER_EMPTY 

Remarks 

For a detailed description of this call see the chapter “Character Device Monitors” in the IBM Operating 
System/2 Version 1.2 I/O Subsystems And Device Support Volume 1. 


C Language 

Idefine 1NCL_D0SM0NIT0RS 

USHORT rc = DosMonRead (Bufferl, WaitFlag, DataBuffer, Bytecnt); 


PBYTE 

Bufferl; 

/* Monitor input buffer */ 

UCHAR 

WaitFlag; 

/* Block/Run indicator */ 

PBYTE 

DataBuffer; 

/* Buffer into which records are read */ 

PUSHORT 

Bytecnt ; 

/* Input /output parm-#bytes (returned) */ 

USHORT 

rc; 

/* return code */ 


i 
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DosMonRead - 

Read Input from Monitor Structure 


XPM 


Assembler Language 

EXTRN DosMonRead: FAR 
INCL_D0SM0NIT0RS EQU 1 

PUSH® OTHER Bufferl ;Monitor input buffer 

PUSH WORD WaitFlag ;Block/Run indicator 

PUSH® OTHER DataBuffer ;Buffer into which records are read 

PUSH© WORD Bytecnt ; Input/output parm-#bytes (returned) 

CALL DosMonRead 

Returns WORD 
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DosMonReg - 

Register Set of Buffers as Monitor 


This call establishes an input and output buffer structure to monitor an I/O stream for a character device. 


DosMonReg (Handle, Bufferl, BufferO, Posflag, Index) 


Parameters 

Handle (HMONITOR) - Input 

Device handle returned from a previous DosMonOpen call. 

Bufferl (PBYTE) - input 

Address of the monitor’s input buffer. The monitor dispatcher moves data records into this buffer 
from the device driver (if the monitor is the first monitor in the monitor chain) or from the previous 
monitor, if any, in the monitor chain. The monitor takes data from this buffer for filtering by calling 
DosMonRead. 

BufferO (PBYTE) - input 

Address of the monitor’s output buffer. The monitor places filtered data into this buffer by calling 
DosMonWrite. The monitor dispatcher moves data records from this buffer to the device driver (if the 
monitor is the last monitor in the monitor chain) or to the next monitor, if any, in the monitor chain. 

Posflag (USHORT) - input 

Used to specify the placement of a monitor’s buffers with the monitor chain (FIRST, LAST or 
DEFAULT) and whether one or two threads are created by the monitor dispatcher to handle data 
movement. 

Value Definition 

0 DEFAULT (no position preference) and one thread for data movement. 

1 FIRST (monitor placed at beginning of monitor chain) and one thread for data movement. 

2 LAST (monitor placed at end of monitor chain) and one thread for data movement. 

3 DEFAULT with two threads for data movement. 

4 FIRST with two threads for data movement. 

5 LAST with two threads for data movement. 

The first monitor in a monitor chain that registers as FIRST is placed at the head of the monitor 
chain. The next monitor that registers as FIRST follows the last monitor registered as FIRST, and so 
on. Similarly, the first monitor that registers as LAST is placed at the end of the monitor chain. The 
next monitor that registers as LAST is placed before the last monitor that registered as LAST, and so 
on. The first monitor that registers as DEFAULT is placed before the last monitor, if any, that regis- 
tered as LAST. The next monitor that registers as DEFAULT is placed before the last monitor that 
registered as DEFAULT, and so on. 

Index (USHORT) - input 

Device specific value. For the keyboard it pertains to the session you wish to register a monitor on. 
For the printer it pertains to the data or code page monitor chain. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOT_ENOUGH_MEMORY 

165 error_monitors_n6t_supported 

379 ERROR_MONJNVALID_PARMS 

381 ERROR_MONJNVALID_HANDLE 

382 ERROR_MON_BUFFER_TOO_SMALL 

Remarks 

For a detailed description of this call see the chapter “Character Device Monitors” in the IBM Operating 
System/2 Version 1.2 I/O Subsystems And Device Support Volume 1. 
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DosMonReg - 

Register Set of Buffers as Monitor 


xPM 


C Language 

#define INODOSMONITORS 

USHORT rc = DosMonReg (Handle, Bufferl, BufferO, Posflag, Index); 


HMONITOR 

Handle; 

/* Monitor handle */ 

PBYTE 

Bufferl ; 

/* Input buffer */ 

PBYTE 

BufferO; 

/* Output buffer ie/ 

USHORT 

Posflag; 

/ie Position flag */ 

USHORT 

Index; 

/* Index */ 

USHORT 

rc; 

/* return code ie/ 


Assembler Language 

EXTRN DosMonReg: FAR 
INCL_DQSMONITORS EQU 1 


PUSH 

WORD 

Handle 

;Monitor handle 

PUSH® 

OTHER 

Bufferl 

; Input buffer 

PUSH® 

OTHER 

BufferO 

;0utput buffer 

PUSH 

WORD 

Posflag 

; Position flag 

PUSH 

WORD 

Index 

; Index 

CALL 

DosMonReg 



Returns WORD 
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xpm DosMonWrite — 

Write Output to Monitor Structure 

This call moves a filtered data record from the monitor's private data area into the monitor’s output 
buffer. 


DosMonWrite (BufferO, DataBuffer, Bytecnt) 


Parameters 

BufferO (PBYTE) - input 

Address of the monitor output buffer. 

DataBuffer (PBYTE) - input 

Address of the monitor’s private data area that contains a filtered data record of length Bytecnt. 
DosMonWrite moves this filtered data record into the monitor’s output buffer. 

Bytecnt ( USHORT) - input 

Number of bytes in the data record. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOT_ENOUGH_M EMORY 

379 ERROR_MONJNVALID_PARMS 

384 ERROR_MON_DATA_TOO_LARGE 

Remarks 

For a detailed description of the use of this call see the chapter “Character Device Monitors” in the IBM 
Operating Systemt2 Version 1.2 I/O Subsystems And Device Support Volume 1. 

C Language 

fdefine INCL_DOSMONITORS 

USHORT rc = DosMonWrite (BufferO, DataBuffer, Bytecnt); 

PBYTE BufferO; /* Monitor output buffer */ 

PBYTE DataBuffer; /* Buffer from which records are taken */ 

USHORT Bytecnt; /* Number of bytes */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosMonWrite: FAR 
INCLJJOSMONITORS EQU 1 

PUSH® OTHER BufferO ;Monitor output buffer 

PUSH© OTHER DataBuffer ; Buffer from which records are taken 

PUSH WORD Bytecnt ; Number of bytes 

CALL DosMonWrite 

Returns WORD 
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DosMove - fapi 

Move a File 


This call moves a file object to another location and changes its name. 


DosMove (OldPathName, NewPathName, Reserved) 


Parameters 

OldPathName ( PSZ ) - input 

Address of the old path name of the file to be moved. 

NewPathName (PSZ) - input 

Address of the new path name of the file. 

Reserved ( ULONG ) - input 

Reserved and must be set to zero. 


rc ( USHORT) - return 


Return code descriptions are: 

0 

NO_ERROR 

2 

ERROR_FILE_NOT_FOUND 

3 

ERROR_PATH_NOT_FOUND 

5 

ERROR_ACCESS_DENIED 

17 

ERROR_NOT_SAME_DEVICE 

26 

ERROR_NOT_DOS_DISK 

32 

ERROR_SHARING_VIOLATION 

36 

ERROR_SHARING_BUFFER_EXCEEDED 

87 

ERROR_INVALID_PARAMETER 

108 

ERROR_DRIVE_LOCKED 

206 

ERROR_FILENAME_EXCED_RANGE 

250 

error_circular7ty_requested 

251 

ERROR_DIRECTORY_IN_CDS 

Remarks 



This call is often used to change only the name of a file or subdirectory, allowing the file object to remain 
in the same subdirectory. Global file name characters are not allowed in the source or target name. 

If the paths specified are different, this allows the subdirectory location of the file object to be changed as 
well. If a drive is specified for the target, it must be the same as the one specified or implied by the 
source. 

Any attempts to move a parent subdirectory to one of its descendant subdirectories are rejected, because 
a subdirectory cannot be both an ancestor and a descendant of the the same subdirectory. Any attempts 
by a process to move the current subdirectory or any of its ancestors are also rejected. 

Attributes (times and dates) of the source file object are moved to the target. If read-only files exist in the 
target path, they are not replaced. 

DosQSysInfo is called during initialization by an application to determine the maximum path length 
allowed by OS/2. 

DosMove can be used to change the case of a file on an FSD drive. The following example would change 
the name of the file to "File.Txt". 

DosMove ("file.txtV'Fite.Txt") 
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fapi DosMove - 

Move a File 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restriction applies to DosMove when coding for the DOS mode: 

File names passed to OldPathName and NewPathName are truncated by the system in the DOS mode 
only. The application must truncate all files passed to OldPathName and NewPathName in the OS/2 
mode or an error code is returned. 

C Language 

Ideflne INCL_DOSFILEMGR 

USHORT rc = DosMove (OldPathName, NewPathName, Reserved); 

PSZ OldPathName; /* Old path name string */ 

PSZ NewPathName; /* New path name string */ 

UL0N6 0; /* Reserved (must be zero) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosMove; FAR 
INCL_DOSFILEMGR EQU 1 

PUSH® ASCI I Z OldPathName ;01d path name string 
PUSH® ASCI IZ NewPathName ;New path name string 
PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosMove 

Returns WORD 
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DosMuxSemWait - 

Wait for One of N Semaphores to Clear 


This call blocks a current thread until one of the specified semaphores is cleared. 


DosMuxSemWait (IndexNbr, LIstAddr, Timeout) 

Parameters 

IndexNbr ( PUSHORT) - output 

Address of the index number of the semaphore in the list of semaphores that satisfies the wait 
request. 

LIstAddr (PVOID) - input 

Address of the structure for list of descriptors that define the semaphores to be waited on. 

semcount ( USHORT) 

Number of semaphores. 

sementry ( MUXSEM ) 

Array of MUXSEM structures: 

reserved ( USHORT) 

Reserved; must be zero. 

hsem (HSEM) 

Reference to the semaphore. 

For a system semaphore, this reference is the handle returned by a DosCreateSem or 
DosOpenSem request that granted the requesting thread access to the semaphore. 

For a RAM semaphore, this reference is the address of a doubleword of storage, allocated 
and initialized to zero by the application. This sets the semaphore as unowned. Other than 
initializing the doubleword to zero, an application must not modify a RAM semaphore 
directly; instead it manipulates the semaphore with semaphore function calls. 

Timeout (LONG) - input 

Action taken by the requesting thread when none of the semaphores in the list is available. The 
values that can be specified are: 

Value Definition 

—1 The requesting thread waits indefinitely for a semaphore to be cleared. 

0 The requesting thread returns immediately. 

> 0 The requesting thread waits the indicated number of milliseconds for a semaphore to be 

cleared before resuming execution. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

95 ERRORJNTERRUPT 

101 ERROR_EXCL_SEM_ALREADY_OWNED 

121 ERROR_SEM_TIMEOUT 

1 51 ERROR J NVALID_EVENT_COUNT 

152 ERROR_TOO_MANY_MUXWAITERS 

153 ERRORJNVALID_LIST_FORMAT 
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DosMuxSemWait - 
Wait for One of N Semaphores to Clear 

Remarks 

DosMuxSemWait checks a semaphore list. If any of the semaphores are clear, DosMuxSemWait returns. 

If all are set, DosMuxSemWait blocks until one of the semaphores is cleared or until the time out occurs. 

Unlike other semaphore calls that block (DosSemRequest, DosSemWait, and DosSemSetWait), 
DosMuxSemWait is an edge-triggered, rather than a level-triggered, procedure. This means it returns 
whenever one of the semaphores on the list is cleared, regardless of how long that semaphore may 
remain clear. It is possible the semaphore may be reset before DosMuxSemWait returns. If a 
semaphore is cleared and then set prior to the thread's executing the DosMuxSemWait call, the event is 
lost. Events are only effective while a thread is in a DosMuxSemWait call. 

This implementation allows DosMuxSemWait to be used in conjunction with one or more semaphores as 
a triggering or synchronizing device. One or more threads can call DosMuxSemWait for a particular 
semaphore. When an event occurs, another thread can clear the semaphore and then immediately set it 
again, arming it for the next event. Threads that were waiting on that semaphore return from 
DosMuxSemWait and resume execution. 

C Language 

typedef struct _MUXSEMLIST { /* mxsl */ 

USHORT cmxs; /* count of MuxSem structures */ 

MUXSEM amxs[16] ; /* MuxSem structure */ 

} MUXSEMLIST; 

typedef struct _MUX$EM { /* mxs */ 

USHORT zero; /* zero */ 

HSEM hsem; /* semaphore handle */ 

} MUXSEM; 

#define INCL_DOSSEMAPHORES 

USHORT rc = DosMuxSemWait (IndexNbr, ListAddr, Timeout); 

PUSHORT IndexNbr; /* Index number of event (returned) */ 

PVOID ListAddr; /* Semaphore list */ 

LONG Timeout; /* Timeout (in milliseconds) */ 

USHORT rc; /* return code */ 

Assembler Language 

MUXSEMLIST struc 

mxsl_cmxs dw ? ; count of MuxSem structures 

mxsl_amxs dw (size MUXSEM)/2 * 16 dup (?) ;MuxSem structure 

MUXSEMLIST ends 

MUXSEM struc 

mxs_zero dw ? ;zero 
mxs_hsem dd ? ; semaphore handle 

MUXSEM ends 

EXTRN DosMuxSemWait: FAR 
INCL_DOSSEMAPHORES EQU 1 

PUSH? WORD IndexNbr ; Index number of event (returned) 

PUSH? OTHER ListAddr Semaphore list 

PUSH DWORD Timeout ;Timeout (in milliseconds) 

CALL DosMuxSemWait 

Returns WORD 
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DosMuxSemWait - 

Wait for One of N Semaphores to Clear 


Example 

The following example illustrates notification of events between threads of the same process. The main 
thread sets two RAM semaphores and invokes two threads, each of which clears one of the semaphores. 
Meanwhile, the main thread waits for either of the two semaphores to clear, and then resumes execution, 
indicating the thread that notified first. 

Idefine INCL_D0SPR0CES$ 

Idefine INCL_DOS$EMAPHORES 

linclude<os2.h> 

#include<stdio.h> 

Idefine NUM_$EMS 2 /* Number of semaphores to wait on */ 

Idefine TIMEOUT 2000L /* Timeout period */ 

Idefine SLEEPTIME 1000L /* Sleep period for Thread_l */ 

Idefine RETURN_CODE G /* Return Code for thread termination */ 

ULONG RamSeml = 0L; /* Allocation and initialization of */ 

ULONG RamSem2 « 0L; /* two RAM semaphores */ 

ULONG far * RamSeml Handle = SRamSeml; /* Semaphore handles */ 

ULONG far *RamSem2Handle - &RamSem2; 

TID Threadl D[2] ; /* Thread Identification */ 

BYTE ThreadStackl[4O0O]; /* Thread Stack Area */ 

BYTE ThreadStack2[4O0O] ; 

MUXSEMLIST SemList; /* Semaphore list structure */ 

USHORT IndexNbr; /* Index number for DosMuxSemWait */ 

USHORT rc; /* Return Code */ 

VOID API ENTRY Thread_l() 

{ 

USHORT r; 

printf (“Begin Thread_l. It will sleep for 1 second. \n“); 

/* Give Thread_2 a chance to execute */ 

DosSleep(SLEEPTIME) ; /* Sleep Interval */ 

if (! (r=DosSemClear(RamSemlHandle))) /* Semaphore handle */ 
printf (“RamSeml cleared. \n“); 

DosExit(EXIT_THREAD, /* Action Code */ 

RETURN_CODE); /* Result Code */ 

} 

VOID APIENTRY Thread 2() 

{ 

USHORT r; 

printf (“Begin Thread_2. It will try to clear RamSem2 now. \n“); 
i f ( ! ( r c DosSemCl ear ( RamSem2Handl e) ) ) /* Semaphore Handle */ 
printf( M RamSem2 cleared. \n“); 

DosExit(EXIT_THREAD, /* Action Code */ 

RETURN_CODE) ; /* Result Code */ 
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DosMuxSemWait - 
Wait for One of N Semaphores to Clear 


main() 

{ 

USHORT rc; /* Return Code */ 

/* Set both semaphores */ 

if(!(rc=DosSemSet(RamSemlHandle))) /* Semaphore Handle */ 
printf ("RamSeml set. \n"); 

if(! (rc»DosSemSet(RamSem2Handle))) /* Semaphore Handle */ 
printf ("RamSem2 set. \n“); 

/* Initialize Semaphore list structure */ 

SemLi st . cmxs = NUM_$EM$; /* Number of semaphores */ 

SemList.amxs[0] .zero =0; /* This field must be 0 */ 

SemLi st. amxs[l]. zero = 0; /* This field must be 0 */ 

SemLi st.amxs[0].hsem s RamSemlHandle; /* Semaphore handle */ 
SemLi st. amxs[l] .hsem = RamSem2Handle; /* Semaphore handle */ 


/* Start the two threads */ 
i f ( ! ( DosCreateThread ( ( PFNTHREAD) Thread 1, 
&ThreadID[0], 
&ThreadStackl [3999] ) ) ) 
printf (“Thread_l created. \n“); 
if (! (DosCreateThread( (PFNTHREAD) Thread_2, 
&ThreadID[l], 
&ThreadStack2 [3999] ) ) ) 
printf (”Thread_2 created. \n"); 


/* Thread address */ 

/* Thread ID (returned) */ 
/* End of thread stack */ 

/* Thread address */ 

/* Thread ID (returned) */ 
/* End of thread stack */ 


fie Wait for either semaphore to clear; then, indicate which */ 
/* thread notified first. */ 


i f ( ! (DosMuxSemWait (&IndexNbr, /* Index of semaphore */ 

jie cleared (returned) */ 

&SemList, /* Address of sem. list structure */ 
TIMEOUT))) lie Timeout period */ 
printf (“Back to main thread; semaphore cleared by Thread%d.\n‘\ 
IndexNbr +1); 

} 

> 
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DosNewSize - 
Change File Size 


FAPI 


This call changes the size of a file. 


DosNewSize (FileHandle, FileSize) 

Parameters 

FileHandle ( HFILE ) - input 

Handle of the file whose size is being changed. 

FileSize ( ULONG ) - input 
File's new size in bytes. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

6 ERRORJNVALIDJHANDLE 

26 ERROR_NOT_DOS_DISK 

33 ERRORJ_OCK_VIOLATION 

87 ERRORJNVALID.PARAMETER 

112 ERROR_DISK_FULL 

Remarks 

When DosNewSize is called, the file must be open in a mode that allows write access. If the file is a 
read-only file, its read-only status must be changed with DosSetFileMode before you can open the file for 
write access. 

The open file can be truncated or extended in size. If the file is being extended, the file system makes a 
reasonable attempt to allocate the additional bytes for the file in a contiguous (or nearly contiguous) 
space on the medium. The value of the new bytes is undefined. 

C Language 

#def i ne INCLJ30SFILEMGR 

USHORT rc ■= DosNewSi ze(FileHand1e, FileSize); 

HFILE FileHandle; /* File handle */ 

ULONG FileSize; /* File's new size */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosNewSize: FAR 
INCL_DOSFILEMGR EQU 1 

PUSH WORD FileHandle ; Fi 1 e handle 

PUSH DWORD FileSize ;File's new size 

CALL DosNewSi ze 

Returns WORD 
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FAPI 


DosOpen - 
Open File 


This call opens a new file, an existing file, a replacement for an existing file, a named pipe, or a device. 


DosOpen (FileName, FileHandle, ActionTaken, FlleSize, FileAttrlbute, OpenFlag, 
OpenMode, Reserved) 


Parameters 

FileName (PSZ) - input 

Address of the ASCI1Z path name of the file, named pipe, or device to be opened. 

FileHandle (PHFILE) - output 

Address of the handle for the file, named pipe, or device. 

ActionTaken ( PUSHORT) - output 

Address of the action taken as a result of DosOpen. 


Value 

Definition 

0001 H 

File exists 

0002H 

File created 

0003H 

File replaced. 


FlleSize (ULONG) - input 

File's new logical size (EOD), in bytes. This parameter is significant only when creating a new file or 
replacing an existing file. Otherwise, it is ignored. 

FileAttrlbute ( USHORT) - input 

File attribute bits. Defined below: 

Bit Description 

15-6 Reserved and must be zero. 

5 File archive 

4 Subdirectory 

3 Reserved and must be zero. 

2 System file 

1 Hidden file 

0 Read only file 

These bits may be set individually or in combination. For example, an attribute value of 0021 H (bits 5 
and 0 set to 1) indicates a read-only file that should be archived. 

OpenFlag (USHORT) - input 

One-word field indicates the action to be taken if the file exists or does not exist. 

Bit Description 

15 -8 Reserved and must be zero. 

7-4 0000 = Fail if file does not exist. 

0001 = Create file if file does not exist. 

3-0 0000 = Fail if the file already exists. 

0001 = Open the file if it already exists. 

0010 = Replace the file if it already exists. 
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DosOpen 
Open File 


FAPI 


OpenMode (USHORT) - input 

The OpenMode parameter contains the following bit flags: 

Bit Description 

15 DASD Open flag: 

0 = FileName represents a file to be opened in the normal way. 

1 = FileName is “Drive:” and represents a mounted disk or diskette volume to be 
opened for direct access. 

14 Write-Through flag: 

0 = Writes to the file may be run through the file system buffer cache. 

1 = Writes to the file may go through the file system buffer cache but the sectors are 
written (actual file I/O completed) before a synchronous write call returns. This state of 
the file defines it as a synchronous file. For synchronous files, this is a mandatory bit in 
that the data must be written out to the medium for synchronous write operations. 

This bit is not inherited by child processes. 

13 Fail-Errors flag. Media I/O errors are handled as follows: 

0 = Reported through the system critical error handler. 

1 = Reported directly to the caller by way of return code. 

Media I/O errors generated through an IOCTL Category 8 function always get reported 
directly to the caller by way of return code. The Fail-Errors function applies only to 
non-IOCTL handle-based file I/O calls. 

This bit is not inherited by child processes. 

12 No-Cache/Cache flag: 

0 = It is advisable for the disk driver to cache the data in I/O operations on this file. 

1 = I/O to the file need not be done through the disk driver cache. 

This bit advises FSDs and device drivers whether it is worth caching the data. Like the 
write-through bit, this is a per-handle bit and is not inherited by child processes. 

11 Reserved and must be zero. 

10-8 The locality of reference flags contain information about how the application is to access 
the file. 

Value Definition 

000 No locality known. 

001 Mainly sequential access. 

010 Mainly random access. 

011 Random with some locality. 

7 Inheritance flag: 

0 = File handle is inherited by a spawned process resulting from a DosExecPgm call. 

1 = File handle is private to the current process. 

This bit is not inherited by child processes. 

6 -4 Sharing Mode flags. This field defines any restrictions to file access placed by the caller 

on other processes: 

Value Definition 

001 Deny Read/Write access 

010 Deny Write access 

011 Deny Read access 

100 Deny neither Read or Write access (Deny None). 

Any other value is invalid. 
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DosOpen - 
Open File 


3 Reserved and must be zero. 

2-0 Access Mode flags. This field defines file access required by the caller: 

Value Definition 

000 Read - Only access 

001 Write - Only access 

010 Read/Write access. 

Any other value is invalid. 

Any other combinations are invalid. 

File sharing requires the cooperation of sharing processes. This cooperation is communicated 
through sharing and access modes. Any sharing restrictions placed on a file opened by a process 
are removed when the process closes the file with a DosClose request. 

Sharing Mode 

Specify the type of access other processes may have to the file (sharing mode). For example, if 
it is permissible for other processes to continue reading the file while your process is operating 
on it, specify Deny Write. This sharing mode prevents other processes from writing to the file 
but still allows them to read it. 

Access Mode 

Specify the type of access to the file needed by your process (access mode). For example, if 
your process requires Read/Write access, and another process has already opened the file with 
a sharing mode of Deny None, your DosOpen request succeeds. However, if the file is open with 
a sharing mode of Deny Write, your process is denied access. 

If the file is inherited by a child process, all sharing and access restrictions are also inherited. 

If an open file handle is duplicated by a call to DosDupHandle, all sharing and access restrictions are 
also duplicated. 

Reserved ( ULONG ) - input 

Reserved and must be set to zero. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOT_FOUND 

3 ERROR_PATH_NOT_FOUND 

4 ERROR’TOOJ4ANY_OPEN_FILES 

5 ERROR_ACCESS_DENIED 

12 ERROR JNVALID_ACCESS 

26 ERROR_NOT_DOS_DISK 

32 ERROR_SHARING_VIOLATION 

36 ERROR_SHARING_BUFFER_EXCEEDED 

82 ERROR_CANNOTJMAKE 

87 ERRORJNVALID_PARAMETER 

108 ERROR_DR!VE_LOCKED 

110 ERROR_OPEN_FAILED 

112 ERROR_DISK_FULL 

206 ERROR_FILENAME_EXCED_RANGE 

231 ERROR_PIPE_BUSY 

99 ERROR__DEVICEJN_USE 
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DosOpen - fapi 

Open File 


Remarks 

A successful DosOpen request for a file returns a handle to access the file. The read/write pointer is set 
at the first byte of the file. The pointer’s position may be changed by a DosChgFilePtr request or by read 
and write operations on the file. 

The file’s date and time can be queried by calling DosQFilelnfo, and set by calling DosSetFilelnfo. 

FileAttribute sets attribute bits for the file object. Attributes of an existing file can be queried and set by 
DosQFileMode and DosSetFileMode. A file’s read-only attribute may also be set with the OS/2 ATTRIB 
command. 

FileAttribute cannot be set to Volume Label. Volume labels cannot be opened. DosSetFSInfo may be 
issued with a logical drive number to set volume label information. 

The FileSize parameter affects the size of the file only when the file is a new file or a replacement for an 
existing one. If an existing file is simply opened, FileSize is ignored. DosNewSize may be called to 
change the existing file’s size. 

The value in FileSize is a recommended size for the file. If allocation of the full size fails, the open may 
still succeed. The file system makes a reasonable attempt to allocate the new size in as nearly contig- 
uous an area as possible on the medium. When the file size is extended, the value of the new bytes is 
undefined. 

The DASD Open bit provides direct access to an entire disk or diskette volume, independent of the file 
system. This mode of opening the volume currently mounted on the drive returns a handle to the caller, 
which represents the logical volume as a single file. The caller specifies this handle with a DosDevlOCtl 
Category 8 Function 0 request to block other processes from accessing the logical volume. 

The file handle state bits can be set by the DosOpen and DosSetFHandState requests. An application can 
query the file handle state bits as well as the rest of the Open Mode field, by calling DosQFHandState. If 
a program running with the NEWFILES bit set tries to create or replace a file with blanks immediately 
preceding the dot on a FAT drive, the system rejects the name. For example, if c: is a FAT drive, the 
name “file .txt” is rejected and the name “file.txt" is accepted. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to DosOpen when coding for the DOS mode: 

• OpenMode restrictions: 

- Handles returned in response to DASD open are valid only for DosDevlOCtl. 

- Inheritance flag Is not supported in DOS 2.X. 

- Write-Through flag must be set to zero. 

- Fail-errors flag must be set to zero. 

- Sharing mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not 
loaded. Sharing mode is not supported in DOS 2.X. 

“ Access mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not 
loaded. Access mode field is not supported in DOS 2.X. 

• Access mode is valid only if Sharing is loaded. 

Named Pipe Considerations 

DosOpen opens the client end of a pipe by name and returns a handle. The open succeeds only if the 
pipe is in a listening state; otherwise, the open returns with ERROR_PIPE_BUSY. The pipe can be busy 
because of the following reasons: 

• All instances of the pipe are already open. 

• The pipe is closed but is not yet disconnected by the serving end. 

• No DosConnectNmPipe is issued against the pipe after it is disconnected. 
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Open File 


Once a given instance has been opened by a client, that same instance cannot be opened by another 
client at the same time. Pipes can only be two-ended; however, the opening process can duplicate the 
open handle as many times as desired. 

Pipes are always opened with the pipe-specific states set to B = 0 (to block reads/writes) and RR = 00 
(read the pipe as a byte stream). The client can change these modes by calling DosSetNmPHandState if 
desired. 


The access and sharing modes specified on the open must be consistent with those specified on the 
DosMakeNmPipe request. 

C Language 

Idefine INCL_DOSFIL£KGR 

USHORT rc «* DosOpen (FileName. FileHandle. ActionTaken, FileSize, 

FileAttribute, OpenFlag, OpenMode, Reserved); 


PSZ 


FileName; 

/* 

File path name string ief 

PHFILE 


FileHandle; 

/* 

File handle (returned) */ 

PUSHORT 

ActionTaken; 

/* 

Action taken (returned) ief 

ULONG 


FileSize; 

/* 

File primary allocation */ 

USHORT 


FileAttribute; /* 

File Attribute */ 

USHORT 


OpenFlag; 

/* 

Open function type ief 

USHORT 


OpenMode; 

/* 

Open mode of the file ief 

ULONG 


0; 

/* 

Reserved (must be zero) ief 

USHORT 


rc; 

/* 

return code ief 

Assembler Language 


EXTRN 

DosOpen: FAR 



INCL_DO$FILEMGR EQU 1 



PUSH® 

ASCI IZ 

FileName 

;File path name string 

PUSH© 

WORD 

FileHandle 

; Fi 1 e handle (returned) 

PUSH® 

WORD 

ActionTaken 

; Action taken (returned) 

PUSH 

DWORD 

FileSize 

;File primary allocation 

PUSH 

WORD 

FileAttribute 

; Fi 1 e Attribute 

PUSH 

WORD 

OpenFl ag 

;0pen function type 

PUSH 

WORD 

OpenMode 

;0pen mode of the file 

PUSH 

DWORD 

0 

; Reserved (must be zero) 

CALL 

DosOpen 





Returns WORD 
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Example 

This example opens a file. 

Idefine INCLJ50SFILEMGR 

Idefine 0PEN_FILE OxGl 
Idefine CREATE FILE 0x10 
Idefine FILE ARCHIVE 0x20 
Idefine FILE EXISTS 0PEN_FILE 
Idefine FILE_NOEXISTS CREATE_FILE 
Idefine DASD FLAG 0 
Idefine INHERIT 0x80 
Idefine WRITE.THRU 0 
Idefine FAIL FLAG 0 
Idefine SHARE_FLAG 0x10 
Idefine ACCESS_FLAG 0x02 

Idefine FILE NAME "test.dat" 

Idefine FILE_SIZE 800L 

Idefine FILE ATTRIBUTE FILE_ARCHIVE 

Idefine RESERVED 0L 

HFILE FileHandle; 

USHORT Wrote; 

USHORT Action; 

PS2 FileData[100] ; 

USHORT rc; 

Action = 2; 

strcpy(FileData, "Data..."); 

rc * DosOpen (FILENAME, /* File path name */ 

&FileHandle, /* File handle */ 

SAction, /* Action taken */ 

FILEJ5IZE, /* File primary allocation */ 

FILE_ATTRIBUTE, /* File attribute */ 

FILEJ-XISTS j FILEJIOEXISTS, /* Open function type */ 

DASD_FLAG | INHERIT \ /* Open mode of the file */ 

WRITE THRU j FAIL_FLAG | 

SHARE_FLAG j ACCESSJLAG, 

RESERVED); /* Reserved (must be zero) */ 
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This call opens a new file, an existing file, or a replacement for an existing file. The opened file can have 
extended attributes. 


DosOpen2 (FileName, FileHandle, ActlonTaken, FileSlze, FileAttribute, OpenFlag, 
OpenMode, EABuf, Reserved) 


Parameters 

FileName ( PSZ ) - input 

Address of the ASCIIZ path name of the file to be opened. 

FileHandle (PHFILE) - output 

Address of the handle for the file. 

ActlonTaken (PUSHORT) - output 

Address of the action taken as a result of DosOpen2. 


Value 

Definition 

0001 H 

File exists 

0002H 

File created 

0003H 

File replaced. 


FileSlze (ULONG) - input 

File’s new logical size (EOD), in bytes. This parameter is significant only when creating a new file or 
replacing an existing file. Otherwise, it is ignored. 

FileAttribute (USHORT) - input 

File attribute bits. Defined below: 

Bit Description 

15 “6 Reserved and must be zero. 

5 File archive 

4 Subdirectory 

3 Reserved and must be zero. 

2 System file 

1 Hidden file 

0 Read only file 

These bits may be set individually or in combination. For example, an attribute value of 0021 H (bits 5 
and 0 set to 1) indicates a read-only file that should be archived. 

OpenFlag ( USHORT) - input 

One-word field indicates the action to be taken if the file exists or does not exist. 

Bit Description 

15-8 Reserved and must be zero. 

7-4 0000 = Fail if file does not exist 

0001 = Create file if file does not exist. 

3-0 0000 = Fail if the file already exists. 

0001 = Open the file if it already exists. 

0010 = Replace the file if it already exists. 
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OpenMode ( ULONG ) - input 

The OpenMode parameter contains the following bit flags: 

Bit Description 

15 DASD Open flag: 

0 = FileName represents a file to be opened in the normal way. 

1 = FileName is "Drive:” and represents a mounted disk or diskette volume to be 
opened for direct access. 

14 Write-Through flag: 

0 = Writes to the file may be run through the file system buffer cache. 

1 = Writes to the file may go through the file system buffer cache but the sectors are 
written (actual file I/O completed) before a synchronous write call returns. This state of 
the file defines it as a synchronous file. For synchronous files, this is a mandatory bit in 
that the data must be written out to the medium for synchronous write operations. 

This bit is not inherited by child processes. 

13 Fail-Errors flag. Media I/O errors are handled as follows: 

0 = Reported through the system critical error handler. 

1 = Reported directly to the caller by way of return code. 

Media I/O errors generated through an IOCTL Category 8 function always get reported 
directly to the caller by way of return code. The Fail-Errors function applies only to 
non-IOCTL handle-based file I/O calls. 

This bit is not inherited by child processes. 

1 2 No-Cache/Cache flag: 

0 = It is advisable for the disk driver to cache the data in I/O operations on this file. 

1 = I/O to the file need not be done through the disk driver cache. 

This bit advises FSDs and device drivers whether it is worth caching the data. Like the 
write-through bit, this is a per-handle bit and is not inherited by child processes. 

11 Reserved and must be zero. 

10-8 The locality of reference flags contain information about how the application is to access 
the file. 

Value Definition 

000 No locality known. 

001 Mainly sequential access. 

010 Mainly random access. 

011 Random with some locality. 

7 Inheritance flag: 

0 = File handle is inherited by a spawned process resulting from a DosExecPgm call. 

1 = File handle is private to the current process. 

This bit is not inherited by child processes. 

6—4 Sharing Mode flags. This field defines any restrictions to file access placed by the caller 

on other processes: 

Value Definition 

001 Deny Read/Write access 

010 Deny Write access 

011 Deny Read access 

100 Deny neither Read or Write access (Deny None). 

Any other value is invalid. 
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3 Reserved and must be zero. 

2 — 0 Access Mode flags. This field defines file access required by the caller: 

Value Definition 

000 Read - On ly access 

001 Write - Only access 

010 Read/Write access. 

Any other value is invalid. 

Any other combinations are invalid. 

File sharing requires the cooperation of sharing processes. This cooperation is communicated 
through sharing and access modes. Any sharing restrictions placed on a file opened by a process 
are removed when the process closes the file with a DosClose request. 

Sharing Mode 

Specify the type of access other processes may have to the file (sharing mode). For example, if 
it is permissible for other processes to continue reading the file while your process is operating 
on it, specify Deny Write. This sharing mode prevents other processes from writing to the file 
but still allows them to read it. 

Access Mode 

Specify the type of access to the file needed by your process (access mode). For example, if 
your process requires Read/Write access, and another process has already opened the file with 
a sharing mode of Deny None, your DosOpen2 request succeeds. However, if the file is open 
with a sharing mode of Deny Write, your process is denied access. 

If the file is inherited by a child process, all sharing and access restrictions are also inherited. 

If an open file handle is duplicated by a call to DosDupHandle, all sharing and access restrictions are 
also duplicated. 

EABuf (PEAOP) - input/output 

Address of the extended attribute buffer, which contains an EAOP structure. An EAOP structure has 
the following format: 

fpGEALIst (PGEALIST) 

Address of GEAList. GEAList is a packed array of variable length "get EA" structures, each con- 
taining an EA name and the length of the name. 

fpFEALIst {PFEALIST) 

Address of FEAList. FEAList is a packed array of variable length "full EA" structures, each con- 
taining an EA name and its corresponding value, as well as the lengths of the name and the 
value. 

oError ( ULONG ) 

Offset into structure where error has occurred. 

On input, the fpGEAList field and oError fields are ignored. The EA setting operation is performed on 
the information contained in FEAList. If extended attributes are not to be defined or modified, then 
EABuf must be set to null. Following is the FEAList format: 

cbLIst (ULONG) 

Length of the FEA list, including the length itself, 
list (FEA) 

List of FEA structures. An FEA structure has the following format: 

Flags (BYTE) 

Bit indicator describing the characteristics of the EA being defined. 

Bit Description 

15 Critical EA. 

14-0 Reserved and must be set to zero. 
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If bit 15 is set to 1, this indicates a critical EA. If bit 15 is 0, this means the EA is noncritical; 
that is, the EA is not essential to the intended use by an application of the file with which it is 
associated. 

cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character 
cbValue (USHORT) 

Length of EA value, which cannot exceed 64KB. 
szName ( PSZ ) 

Address of the ASCIIZ name of EA. 
aValue (PSZ) 

Address of the free-format value of EA. 

Note: The szName and aValue fields are not included as part of header or include files. 

Because of their variable lengths, these entries must be built manually. 

On output, fpGEAList Is unchanged. fpFEAList is unchanged as is the area pointed to by fpFEAList. If 
an error occurred during the set, oError is the offset of the FEA where the error occurred. The API 
return code is the error code corresponding to the condition generating the error. If no error 
occurred, oError is undefined. 

If EABuf is 0x00000000, then no extended attributes are defined for the file. 

Reserved (ULONG) - input 

Reserved and must be set to zero. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOT_FOUND 

3 E R RO R_P ATH_NOT_FO U N D 

4 E R RO R_T 00_M AN Y_0 P EN_FI L ES 

5 ERROR_ACCESS_DENIED ~ 

12 ERROR JNVALID_ACCESS 

26 ERROR_NOT_DOS_DISK 

32 ERROR_SHARING~VIOLATION 

36 ERROR_SHARING_BUFFER_EXCEEDED 

82 ERROR_CANNOT_MAKE 

87 ERRORJNVALID>ARAMETER 

108 ERROR_DRIVEJ_OCKED 

110 ERROR_OPEN_F AILED 

112 ERRORJDISK_FULL 

206 ERROR_FILENAME_EXCED_RANGE 

231 ERROR_PIPE_BUSY 

99 ERROR_DEVICE_INJJSE 

Remarks 

A successful DosOpen2 request for a file returns a handle to access the file. The read/write pointer is set 
at the first byte of the file. The pointer's position may be changed by a DosChgFilePtr request or by read 
and write operations on the file. 

The file’s date and time can be queried by calling DosQFilelnfo, and is set by calling DosSetFilelnfo. 

FileAttribute sets attribute bits for the file object. Attributes of an existing file can be queried and set by 
DosQFileMode and DosSetFileMode. A file’s read-only attribute may also be set with the OS/2 ATTRIB 
command. 

FileAttribute cannot be set to Volume Label. Volume labels cannot be opened. DosSetFSinfo may be 
issued with a logical drive number to set volume label information. 
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The FileSize parameter affects the size of the file only when the file is a new file or a replacement for an 
existing one. If an existing file is simply opened, FileSize is ignored. DosNewSize may be called to 
change the existing file’s size. 

The value in FileSize is a recommended size for the file. If allocation of the full size fails, the open may 
still succeed. The file system makes a reasonable attempt to allocate the new size in as nearly contig- 
uous an area as possible on the medium. When the file size is extended, the value of the new bytes is 
undefined. 

The DASD Open bit provides direct access to an entire disk or diskette volume, independent of the file 
system. This mode of opening the volume currently mounted on the drive returns a handle to the caller, 
which represents the logical volume as a single file. The caller specifies this handle with a DosDevlOCtl 
Category 8 Function 0 request to block other processes from accessing the logical volume. 

The file handle state bits can be set by the DosOpen2 and DosSetFHandState requests. An application 
can query the file handle state bits as well as the rest of the Open Mode field, by calling 
DosQFHandState. 

Extended attributes can be set by an EAOP structure in EABuf when creating a file, replacing an existing 
file, or truncating an existing file. No extended attributes are set when simply opening an existing file. 

A replace operation is logically equivalent to atomically deleting and re-creating the file. This means that 
any extended attributes associated with the file are also deleted before the file is re-created. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to DosOpen when coding for the DOS mode: 

• OpenMode restrictions: 

- The high word of OpenMode is ignored and is not error checked. 

- Handles returned in response to DASD open are valid only for DosDevlOCtl. 

- Inheritance flag is not supported in DOS 2.X. 

- Write-Through flag must be set to zero. 

- Fail-errors flag must be set to zero. 

- Sharing mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not 
loaded. Sharing mode is not supported in DOS 2.X. 

- Access mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not 
loaded. Access mode field is not supported in DOS 2.X. 

• Access mode is valid only if Sharing is loaded. 
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C Language 

typedef struct _6EA { /* gea */ 

BYTE cbNape; /* nape length not including NULL */ 

CHAR szName[l]; /* attribute name */ 

} GEA; 

typedef struct _GEALIST { /* geal */ 

ULONG cbList; /* total bytes of structure including full list */ 

GEA 1 i st [1] ; /* variable length GEA structures */ 

} GEALIST; 

typedef struct _FEA { /* fea */ 

BYTE fEA; /* flags */ 

BYTE cbName; /* name length not including NULL */ 

USHORT cbValue; /* value length */ 

} FEA; 

typedef struct REALIST { /* feal */ 

ULONG cbList; /* total bytes of structure including full list */ 

FEA list [13 ; /* variable length FEA structures */ 

} FEALIST ; 

typedef struct _EA0P { /* eaop */ 

PGEALIST fpGEAList; /* general EA list */ 

PFEALIST fpFEAList; /* full EA list */ 

ULONG oError; 

} EAOP; 

#define INCLJOSFILEMGR 

USHORT rc » Dos0pen2(Fi leName, FileHandle, ActionTaken, FileSize, 

FileAt tribute, OpenFlag, OpenMode, EABuf , Reserved); 


PSZ 

Fi leName; 

/* File path nape string */ 

PHFILE 

FileHandle; 

/* File handle (returned) */ 

PUSHORT 

ActionTaken; 

fie Action taken (returned) ie/ 

ULONG 

FileSize; 

/ie File primary allocation */ 

USHORT 

FileAttribute; /* File Attribute */ 

USHORT 

OpenFlag; 

/ie Open function type ie/ 

ULONG 

OpenMode; 

/ie Open mode of the file ie/ 

PEAOP 

EABuf; 

/ie Extended attribute buffer ie/ 

ULONG 

0; 

/ie Reserved (must be zero) ie/ 

USHORT 

rc; 

/ie return code ie/ 
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Assembler Language 

GEA struc 

gea_cbName db ? jname length not including NULL 

gea_szName db 1 dup (?) ; attribute name 

GEA ends 

GEALIST struc 

geal_cbList dd ? ; total bytes of structure including full list 

gealjist db size GEA * 1 dup (?) ’.variable length GEA structures 

GEALIST ends 

FEA struc 

fea_fEA db ? ; f 1 ags 

fea_cbName db ? ;name length not including NULL 
fea_cbValue dw ? ; value length 

FEA ends 

FEALIST struc 

fealjrbList dd ? ; total bytes of structure including full list 

fealjist db size FEA * 1 dup (?) : variable length FEA structures 

FEALIST ends 

EAOP struc 

eaop fpGEAList dd ? ; general EA list 
eaopJpFEAList dd ? ;full EA list 

eaop_oError dd ? ; 

EAOP ends 

EXTRN Dos0pen2:FAR 
I NCL_D0SFI LEKGR EQU 1 

PUSH® ASCI IZ FileName ;File path name string 

PUSH® WORD FileHandle ; Fi 1 e handle (returned) 

PUSH® WORD ActionTaken ; Action taken (returned) 

PUSH DWORD FileSize ; Fi le primary allocation 

PUSH WORD FileAttribute ; Fi le Attribute 

PUSH WORD OpenFlag ;0pen function type 

PUSH DWORD OpenMode ;0pen mode of the file 

PUSH® OTHER EABuf ; Extended attribute buffer 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL Dos0pen2 

Returns WORD 
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This call opens a queue for the current process. 


DosOpenQueue (OwnerPID, QueueHandle, QueueName) 

Parameters 

OwnerPID ( PUSHORT) - output 

Address of the process ID of the queue owner. 

QueueHandle (PHQUEUE) - output 

Address of the write handle of the queue. 

QueueName ( PSZ ) - input 

Address of the name of the queue provided by a previous DosCreateQueue call. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

334 ERROR_QUE_NO_M EMORY 

343 ERROR_QUEJMAME_NOT_EXIST 

Remarks 

A process that creates a queue has access to it with the handle returned by DosCreateQueue. Before 
another process can place elements in the queue with DosWriteQueue, the process must first obtain the 
queue handle by issuing DosOpenQueue. 

When specifying the name for the queue, the ASCIIZ name string provided must include the prefix 
\QUEUES\. 

C Language 

Idefine INCLJJOSQUEUES 

USHORT rc = DosOpenQueue(OwnerPID, QueueHandle, QueueName); 

PUSHORT OwnerPID; /* Address to put queue owners' PID */ 

PHQUEUE QueueHandle; /* Address to put handle of queue */ 

PSZ QueueName; /* Pointer to queue name string */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosOpenQueue; FAR 

INCL_DOSQUEUES EQU 1 

PUSH? WORD OwnerPID ;Queue owners' PID (returned) 

PUSH? WORD QueueHandle ;Queue handle (returned) 

PUSH? ASCIIZ QueueName ; Queue name string 

CALL DosOpenQueue 

Returns WORD 
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This call opens an existing system semaphore that has been created by another process. 


DosOpenSem (SemHandle, SemName) 


Parameters 

SemHandle (PHSEM) - output 

Address of the handle of the system semaphore created by DosCreateSem. This handle must be 
supplied by any requests directed to the same semaphore. 

SemName (PSZ) - input 

Address of the name of the system semaphore created by using DosCreateSem. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

100 ERROR_TOO_MANY_SEMAPHORES 

123 ERRORJNVALID_NAME 

187 ERROR_SEM_NOTFOUND 

Remarks 

A system semaphore that is created by a call to DosCreateSem with NoExclusive= 1 specified returns a 
handle, which the creating process uses to access the semaphore. Another process that needs to access 
the semaphore must call DosOpenSem after the semaphore’s creation. DosOpenSem merely returns the 
handle of the semaphore; it does not test or change the value of the semaphore. 

If a process has access to any semaphores at the time it issues DosExecPgm to start a child process, the 
new process inherits the handles to these semaphores. However, the new process initially does not own 
any inherited semaphores, even if the parent process owns them at the time the child process is started. 
Semaphore ownership is obtained by a successful DosSemRequest call, and only one process can own 
the semaphore at a time. 

When the last process that opened a particular semaphore with a DosCreateSem or DosOpenSem 
request closes its handle with a DosCloseSem request, the semaphore is deleted from memory and must 
be be redefined by its next user with a call to DosCreateSem. 


C Language 

#define INCLJOSSEMAPHORES 

USHORT rc = DosOpenSem (SemHandle, SemName); 


PHSEM 

SemHandle; 

/* Semaphore handle (returned) */ 

PSZ 

SemName; 

/* Semaphore name string */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosOpenSem: FAR 
I NCL J30SSEMAPHORES EQU 1 

PUSH© DWORD SemHandle ; Semaphore handle (returned) 

PUSH© ASCI IZ SemName Semaphore name string 

CALL DosOpenSem 

Returns WORD 
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Example 

The following example illustrates the notification of an event between threads of different processes. 
Processl creates a nonexclusive system semaphore named processl.sem and sets it. It then invokes 
process2 to run asynchronously. Processl then waits, with a timeout of 4.5 seconds, for process2 to open 
the semaphore and clear it, thereby notifying processl to resume. Notice that there is a small possibility 
of processl missing the notification because process2 may clear the semaphore before processl issues 
DosSemWait. See the example for DosSemSetWait for an alternative that would correct this. 

/* processl. c */ 

#de fine INCL DOSSEMAPHORES 
#define INCL_DOSPROCESS 

linclude <os2.h> 


Idefine SEM_NAME “WSEMWprocessl.sem" /* Semaphore name */ 

#define TIMEOUT 4500L /* Timeout period */ 

#define START_PROGRAM H process2.exe" /* Name of program file */ 

main() 

{ 

HSEM SemHandle; 

CHAR ObjFail [50]; 

PS2 Args; 

PSZ Envs; 

RESULTCODES ReturnCodes; 

USHORT rc; 

printf ("Processl now running. \n M ); 

rc = OosCreateSem(CSEM_PUBLIC f /* Ownership - nonexclusive */ 

&SemHandle, /* Semaphore handle (returned) */ 

$EM_NAME) ; /* Semaphore name string */ 

printf (“Processl.sem created; return code is %d \n u , rc); 

/*** SET the semaphore. ***/ 

if ((rc = DosSemSet (SemHandle))) /* Semaphore handle */ 
/****************************************/ 

/* Cannot set semaphore -- error processing */ 

} 

/* Start a separate process */ 

if(!(DosExecPgm(ObjFail , /* Object name buffer */ 

sizeof (ObjFai 1 ) , /* Length of obj. name buffer */ 

EXEC_ASYNC, /* Execution flag - asynchronous */ 

Args, /* Ptr. to argument string */ 

Envs, f-k Ptr. to environment string */ 

SReturnCodes, /* Ptr. to resultcodes struct. */ 

$TART_PR0GRAM))) /* Name of program file */ 

printf ("Process2 started. Processl will try to wait for notification. \n"); 

/*** WAIT for a notification from process2 on processl.sem ***/ 
if((rc = DosSemWait (SemHandle, /* Semaphore handle */ 

TIMEOUT))) /* Timeout period */ 

/***★★****************************★*★****/ 

/* No notification (either interrupt or timeout); error processing */ 

else 

{ 

/* Notification received. Normal processing */ 

printf (“Process2 cleared semaphore; processl running again. \n"); 

> 
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/* process2.c */ 

Idefine INCL_DOSSEMAPHORES 
#include <os2.h> 

#define SEM_NAME “\\SEM\\processl.sem" /* Semaphore name */ 

main() 

{ 

HSEM SemHandle; 

USHORT rc; 

/* Obtain access to semaphore created by processl via OPEN */ 
if ((rc=DosOpenSem(&SemHandle, /* Semaphore handle (returned) */ 

SEMJAME))) /* Semaphore Name */ 

/*************★************ ******* Icicle** lei?/ 

{ 

/* Could not open — error processing (switch on rc). */ 

} 

else 

{ 

/* Opened semaphore; normal processing. Clear semaphore when done. */ 
printf ("Semaphore OPENED. \n"); 

if(!(rc=DosSemClear(SemHandle))) /* Semaphore handle */ 

printf (“Semaphore CLEARED. \n"); 

} 

> 
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This call reads pipe without removing the read data from the pipe. 


DosPeekNmPipe (Handle, Buffer, BufferLen, BytesRead, BytesAvail, PipeState) 


Parameters 

Handle (HPiPE) - input 

Handle of the named pipe, returned by DosMakeNmPipe or DosOpen. 

Buffer (PBYTE) — output 

Address of the output buffer. 

BufferLen (USHORT) - input 
Number of bytes to be read. 

BytesRead ( PUSHORT) - output 

Address of the number of bytes read. 

BytesAvail (PUSHORT) - output 

Address of the 4-byte buffer where the system returns the number of bytes that were available. The 
buffer structure is: 

2 Bytes Bytes buffered in pipe (including message header bytes and bytes peeked). 

2 Bytes Bytes in current message (zero for a byte stream pipe). 

PipeState (PUSHORT) - output 

Address of a value representing the state of the named pipe. 

Value Definition 

1 Disconnected 

2 Listening 

3 Connected 

4 Closing 

The pipe is in a disconnected state immediately after: 

• A DosMakeNmPipe but before the first DosConnectNmPipe, or 

• A DosDisConnectNmPipe but before the next DosConnectNmPipe. 

A disconnected pipe has no client end and cannot accept a DosOpen. The serving end must issue 
DosConnectNmPipe, so an open can be accepted. 

The pipe is in a listening state after a DosConnectNmPipe. A listening pipe is ready to accept a 
DosOpen request. If the pipe is not in a listening state, DosOpen returns ERROR_PIPE_BUSY. 

The pipe is in a connected state after a successful DosOpen to the listening pipe. The connected 
pipe allows the serving and client ends to perform I/O, provided both have valid handles. 

The pipe is in a closing state after the last DosClose to the pipe from either the client or server end. 

After DosClose has been issued for the client handle and any duplicates, and the serving end has 
read all buffered data, the serving end is returned ERROR_EOF for reads and ERROR_BROKEN_PIPE 
for writes. The serving end must acknowledge the closing of the client end by issuing either 
DosDisConnectNmPipe or DosClose. Issuing DosClose deallocates the pipe. 

rc (USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

230 ERROR_BAD_PIPE 

231 ERROR_PIPE_BUSY 

233 ERROR_P!PE_NOT_CONNECTED 
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Remarks 

DosPeekNmPipe is similar to a DosRead, except the bytes read from the pipe are not removed. In addi- 
tion, a DosPeekNmPipe never blocks, regardless of the blocking mode set. If the pipe cannot be 
accessed immediately, ERROR_PIPE_BUSY is returned. Because the peek cannot block, it returns only 
what is currently in the pipe. Thus, a portion of a message may be returned, even though the size of the 
peek can accommodate the entire message. 

The value returned in PipeState can be used by the client or the server end to determine the current state 
of the pipe and take appropriate action. 

C Language 

#define INCLJJOSNMPIPES 

USHORT rc = DosPeekNmPipe (Handle, Buffer, BufferLen, BytesRead, 

BytesAvail, PipeState); 

HPIPE Handle; /* Pipe handle */ 

PBYTE Buffer; /* Address of user buffer */ 

USHORT BufferLen; /* Buffer length */ 

PUSHORT BytesRead; /* Bytes read (returned) */ 

PUSHORT BytesAvail; /* Bytes available (returned) */ 

PUSHORT PipeState; /* Pipe state (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosPeekNmPipe: FAR 
INCL_DOSNMPIPES EQU 1 

PUSH WORD Handle ;Pipe handle 

PUSH@ OTHER Buffer ;User buffer 

PUSH WORD BufferLen ; Buffer length 

PUSHO WORD BytesRead ; Bytes read (returned) 

PU$H@ DWORD BytesAvail ;Bytes available (returned) 

PUSH@ WORD PipeState ;Pipe state (returned) 

CALL DosPeekNmPipe 

Returns WORD 
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This call retrieves an element from a queue without removing it from the queue. 


DosPeekQueue (QueueHandle, Request, DataLength, DataAddress, ElementCode, 
NoWalt, ElemPriority, SemaphoreHandle) 


Parameters 

QueueHandle ( HQUEUE ) - input 
Handle of the queue to read. 

Request (PULONG) - output 

Address of the data to be filled in with the following information. 

Word Description 

1 The PID of the process that added the element to the queue. 

2 Used for event coding by the application. The data in this word is the same as that fur- 
nished by the Request parameter on the DosWriteQueue request for the corresponding 
queue element. The value of this data is understood by the client thread and by the 
server thread. There is no special meaning to this data and the operating system does 
not alter the data. 

DataLength (PUSHORT) - output 

Address of the length of the received data. 

DataAddress (PULONG) - output 

Address of the element retrieved from the queue. 

ElementCode ( PUSHORT) — input/output 

Address of the code that identifies the element to be read. This field is set to: 

Value Definition 

0 Read the element at the beginning of the queue and return the identifier of the next 

element. 

^0 Read the element whose identifier is specified and return the identifier of the next 

element. 

NoWalt ( UCHAR ) - input 

Action to be performed when there are no entries on the queue, shown below. 

Value Definition 

0 Requesting thread waits 

1 Requesting thread does not wait. 

ElemPriority (PBYTE) - output 

Address of the element's priority. This is the value that was specified for ElemPriority by the 
DosWriteQueue call that added the element to the queue. 

SemaphoreHandle (ULONG) - input 

Handle of a semaphore to be cleared when the queue has data placed into it and NoWait=0 is speci- 
fied. If NoWait=1 is specified, this parameter should be set to null. 

The semaphore may be either a RAM or system semaphore. If this handle is for a RAM semaphore, 
that semaphore must be in a segment shared between the process that owns the queue and any 
process that issues a DosWriteQueue request to the queue. 

If multiple threads are processing elements from the queue using a NoWait=0, the same semaphore 
must be provided on ail DosPeekQueue or DosReadQueue requests. 

rc (USHORT) - return 

Return code descriptions are: 


2-220 Control Program Programming Reference 







DosPeekQueue - 
Peek Queue 

0 NO_ERROR 

330 ERROR_QUE_PROC_NOT_OWNED 

333 ERROR_QUE_ELEMENT_NOT_EXIST 

337 ERROR_QUEJNVALID_HANDLE 

342 ERROR_QUEJEMPTY 

433 ERROR_QUEJNVALID_WAIT 

Remarks 

A process that creates a queue with DosCreateQueue owns it. Only the owning process and any threads 
it creates can issue DosPeekQueue to examine a queue element without removing it from the queue. If 
the queue is empty and NoWalt=0 is specified, the thread waits for an element to be added to the queue. 

If the queue is empty and NoWait=1 is specified, the thread returns with ERROR_QUE_EMPTY. 

The ElementCode parameter returns an indicator for the element being examined. To examine the first 
element in the queue, the queue owner issues DosPeekQueue with ElementCode set to zero. To examine 
the next element in the queue, the queue owner uses the value returned in ElementCode as input for the 
next DosPeekQueue request, and so on. By issuing successive peeks, the queue owner can select a 
queue element and then remove it from the queue by specifying an ElementCode value with a 
DosReadQueue request. 

The semaphore provided by SemaphoreHandle is typically used with a DosMuxSemWait request to wait 
for a queue or any of several other events. If DosReadQueue is issued with NoWait=0, it clears the 
semaphore indicated by SemaphoreHandle as soon as the element is peeked. 

The Request, DataLength and DataBuffer parameters contain data understood by the thread adding the 
element to the queue and by the thread that receives the queue element. There is no special meaning to 
this data; applications may use these parameters for any purpose they wish. OS/2 does not alter this 
data; it simply copies this data intact. OS/2 does not validate the address of DataBuffer or the 
DataLength. 

C Language 

#define INCLJJOSQUEUES 

USHORT rc = DosPeekQueue (QueueHandle, Request, DataLength, DataAddress, 

ElementCode, NoWait, ElemPriority, SemaphoreHandle); 

HQUEUE QueueHandle; /* Queue handle */ 

PULONG Request; /* Request identification data (returned) */ 

PUSHORT DataLength; /* Length of element received (returned) */ 

PULONG DataAddress; /* Address of element received (returned) */ 

PUSHORT ElementCode; /* Indicator of element received (returned) */ 

UCHAR NoWait; /* Indicate to not wait if queue is empty */ 

PBYTE ElemPriority; /* Priority of element (returned) */ 

ULONG SemaphoreHandle; /* Semaphore Handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosPeekQueue:FAR 
INCL_DOSQUEUES EQU 1 

PUSH WORD QueueHandle ; Queue handle 

PUSH© DWORD Request ; Request identification data (returned) 

PUSH© WORD DataLength ; Length of element received (returned) 

PUSH© DWORD DataAddress ; Address of element received (returned) 

PUSH© WORD ElementCode ; Indicator of element received (returned) 

PUSH OTHER NoWait ; Indicate to not wait if queue is empty 

PUSH© BYTE ElemPriority priority of element (returned) 

PUSH DWORD SemaphoreHandle ; Semaphore Handle 

CALL DosPeekQueue 

Returns WORD 
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DosPFSActivate - 
Activate Font 


This call specifies the code page and font to make active for the specified printer and system file number. 


DosPFSActivate (SplHandle, BytesWrltten, PrinterName, CodePage, FontID, SFN, 
Reserved) 


Parameters 

SplHandle ( PVOID ) - input 

Address of the file handle of the temporary spool file that activates code page and font switching. 

BytesWrltten ( PULONG ) — output 

Address of the number of bytes written to the temporary spool file. 

PrinterName (PSZ) - input 

Address of the name of the printer that activates code page and font switching. 

CodePage ( USHORT) - input 

Active code page for the specified printer and system file number. 

FontID ( USHORT) - input 

Active font within the specified code page for the specified printer and system file number. 

For download fonts, the FontID is that specified in the printer font file. 

For cartridge fonts, the FontID is the number specified on the label of the cartridge and in the 
DEVINFO statement for the printer. 

A value of 0 (0000H) for both the CodePage and FontID indicates that the hardware default code page 
and font should be made active. 

A value of 0 for the font ID but not the code page indicates that any font ID is acceptable for the code 
pages. 

SFN (USHORT) - input 

System file number of the requester. The SFN is passed as a parameter in the monitor packet. 

Reserved ( ULONG ) - input 

Reserved must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are listed in following section. 

Remarks 

DosPFSActivate is intended for use only by applications that replace the spooler as a print monitor and 
that do code page switching. Other applications should use printer lOCTLs to manipulate printer code 
page switching. 

DosPFSActivate is located in SPOOLCP.DLL (not in DOSCALLS.LIB) and requires an import statement in 
the module definition file. See the IBM Operating System/2 Version 1.2 Building Programs , Module Defi- 
nition File Statements section for information regarding the import statement. 

Return values are: 

2 Code page not available. 

4 Font ID not available. 

9 Code page switcher internal error. 

10 Invalid printer name as input. 

13 Received code page request when code page switcher not initialized. 

15 System file number table full. Cannot activate another entry. 

19 I/O error reading font file control sequence section. 

21 I/O error reading font file font definition block. 

23 I/O error while writing to temporary spool file. 
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24 Disk full error while writing to temporary spool file. 

25 Bad spool file handle. 

C Language 

#define INCLJ50SPFS 

USHORT rc ■ DosPFSActivate (Spl Handle, BytesWri tten, PrinterName, 

CodePage, Font ID* SFN, Reserved); 


PVOID 


Spl Handle; 

/* Temporary Spool File handle */ 

PULONG 


BytesWri tten 

; /* Number of bytes written (returned) 

PSZ 


PrinterName; 

/* Printer name string */ 

USHORT 


CodePage; 

/* Code Page to make active */ 

USHORT 


Font ID; 

/* Font ID to make active */ 

USHORT 


SFN; 

/* System File Number */ 

ULONG 


0; 

/* Reserved, set to zero */ 

USHORT 


rc; 

/* return code */ 

Assembler Language 

EXTRN 

DosPFSActi vate; FAR 


INCL_DOSPFS 

EQU 1 


PUSH® 

DWORD 

Spl Handle 

temporary Spool File handle 

PUSH® 

DWORD 

BytesWri tten 

;Number of bytes written (returned) 

PUSH® 

ASCI 12 

PrinterName 

; Printer name string 

PUSH 

WORD 

CodePage 

;Code Page to make active 

PUSH 

WORD 

FontID 

;Font ID to make active 

PUSH 

WORD 

SFN 

; System File Number 

PUSH 

DWORD 

0 

Reserved (must be zero) 

CALL 

DosPFSActivate 



Returns WORD 
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DosPFSCIoseUser - 
Close Font User Interface 


This call indicates to the Font Switcher that the specified process has closed its spool file. The Font 
Switcher may then free any resources being used to track code page and font switching for a process. 


DosPFSCIoseUser (PrlnterName, SFN, Reserved) 


Parameters 

PrlnterName (PSZ) - input 

Address of the name of the printer that closes code page and font switching. 

SFN ( USHORT) - input 

System File Number of the requester. The SFN is passed as a parameter in the monitor packet. 

Reserved ( ULONG ) - input 

Reserved must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are listed in the following section. 

Remarks 

DosPFSCIoseUser is intended for use only by applications that replace the spooler as a print monitor and 
that do code page switching. Other applications should use printer lOCTLs to manipulate printer code 
page switching. 

DosPFSCIoseUser is located in SPOOLCP.DLL (not in DOSCALLS.LIB) and requires an import statement 
in the module definition file. Refer to the IBM Operating System 12 Version 1.2 Building Programs , Module 
Definition File Statements section for information regarding the import statement. 

Return values are: 

8 Attempted to close system file number not active. 

9 Code page switcher internal error. 

10 Invalid printer name as input. 

13 Received code page request when code page switcher not initialized. 


C Language 

#define INCL_DOSPFS 

USHORT rc - Do$PFSCloseUser(PrinterName, SFN, Reserved); 


PSZ 

Pri nterName; 

/* 

Printer name string */ 

USHORT 

SFN; 

/* 

System File Number */ 

ULONG 

0; 

/* 

Reserved, set to zero */ 

USHORT 

rc; 

/* 

return code */ 


Assembler Language 

EXTRN DosPFSCl oseUser:FAR 
I NCL_DOSPFS EQU 1 

PUSH@ ASCI IZ PrinterName ; Printer name string 

PUSH WORD SFN ; System File Number 

PUSH DWORD 0 Reserved (must be zero) 

CALL DosPFSCIoseUser 

Returns WORD 
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Initialize Code Page and Font 


This call allows the Font Switcher to initialize code page and font switching for a specified printer. 


DosPFSInit (CPHdw, FontFlleName, PrfnterType, PrlnterName, Instances, Reserved) 


Parameters 

CPHdw (PUSHORT) - input 

Address of the pointer list, in the following format, that specifies the hardware code page and fonts 
on the printer. 

Word Description 

Word 0 Number of definitions that follow. 

DWord 1 / N Code page number (1st Word of DWord) and Font ID (2nd Word of DWord) for each hard- 
ware font in order corresponding to the hardware code page and font selection numbers. 
(For example, the first code page and font ID value corresponds to the default hardware 
font 0, the second, to hardware font 1, the third, to hardware font 2, and so on. If the 
default hardware font is not known, 0 should be specified for the default code page and 
font). 

FontFlleName ( PSZ ) - input 

Address of the pathname of the font file of the specified printer that initiates the code page and font 
switching. 

PrinterType (PSZ) - input 

Address of the printer type ID. 

PrlnterName (PSZ) - input 

Address of the name of the printer that initiates code page and font switching. 

Instances (USHORT) - input 

Maximum number of different instances of use tracking code page and font switching. This value is 
advisory for the Font Switcher allocating enough resources for the specified number of instances 
being tracked. 

Reserved (ULONG) - input 

Reserved must be set to zero. 

rc (USHORT) - return 

Return code descriptions are listed in the following section. 

Remarks 

DosPFSInit is intended for use only by applications that replace the spooler as a print monitor and that do 
code page switching. Other applications should use printer lOCTLs to manipulate printer code page 
switching. 

DosPFSInit is located in SPOOLCP.DLL (not DOSCALLS.LIB) and requires an import statement in the 
module definition file. Refer to the IBM Operating System/2 Version 1.2 Building Programs , Module Defi- 
nition File Statements section for information regarding the import statement. 

Return values are: 

I Code page switcher already initialized 

3 User entered too many ROMs in DEVINFO, initialization continued with the rest 

6 Wrong or missing font file ID 

9 Code page switcher internai error 

10 Invalid printer name as input 

II Printer type input does not match that in font file 

12 Could not get storage for control blocks 

14 Could not open font file during initialization 


Chapter 2. Control Program Function Calls 


2-225 







DosPFSInit - 

Initialize Code Page and Font 


17 Switcher reports too many system file number entries 

19 I/O error reading font file control sequence section 

20 I/O error reading font file header 

21 I/O error reading font file font definition block 

22 Some fonts bad due to error in font file, initialization continued. 

C Language 

Idefine INCL_D0SPFS 

USHORT rc = DosPFSInit (CPHdw, FontFileName, PrinterType, PrinterName, 

Instances, Reserved); 

PUSHORT CPHdw; /* Hdw Font definition list */ 

PSZ FontFileName; /* File pathname of the font file to use */ 

PSZ PrinterType; /* Printer type string */ 

PSZ PrinterName; fie Printer name string ief 

USHORT Instances; /ie Number of spool instances ief 

ULONG 0; /ie Reserved ief 

USHORT rc; fie return code ie/ 

Assembler Language 

EXTRN DosPFSInit: FAR 
INCL_D0SPF$ EQU 1 

PUSH® WORD CPHdw ;Hdw Font definition list 

PUSH® ASCI IZ FontFileName ;File pathname of the font file to use 

PUSH® ASCI IZ PrinterType ; Printer type string 

PUSH® ASCI IZ PrinterName ; Printer name string 

PUSH WORD Instances ;Number of spool instances 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosPFSInit 

Returns WORD 
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Query Active Font 


This call queries the active code page and font for the specified printer and system file number. 


DosPFSQueryAct (PrinterName, CodePage, FontID, SFN, Reserved) 


Parameters 

PrinterName ( PSZ ) - input 

Address of the name of the printer that queries the active code page and font 
CodePage ( PUSHORT) - output 

Address of the active code page that returns the specified printer and System File Number. 

FontID (PUSHORT) - output 

Address of the active Font ID number that returns the specified printer and System File Number. 

SFN (USHORT) - input 

System File Number of the requester. The SFN is passed as a parameter in the monitor packet. 

Reserved (ULONG) — input 

Reserved must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are listed in the following section. 

Remarks 

DosPFSQueryAct is intended for use only by applications that replace the spooler as a print monitor and 
that do code page switching. Other applications should use printer lOCTLs to manipulate printer code 
page switching. 

DosPFSQueryAct is located in SPOOLCP.DLL (not in DOSCALLS.LIB) and requires an import statement 
in the module definition file. Refer to the IBM Operating System/2 Version 1.2 Building Programs , Module 
Definition File Statements section for information regarding the import statement. 

Return values are: 

9 Code page switcher internal error. 

10 invalid printer name as input. 

13 Received code page request when code page switcher not initialized. 

16 Received request for system file number not in the system file number table. 

C Language 

#define INCLJ30SPFS 

USHORT rc = DosPFSQueryAct (PrinterName, CodePage, FontID, SFN, Reserved); 


PSZ 

PrinterName; 

/* Printer name string */ 

PUSHORT 

CodePage; 

/* Code Page return */ 

PUSHORT 

FontID; 

/* Font ID return */ 

USHORT 

SFN; 

fie System File Number */ 

ULONG 

0; 

fie Reserved, set to zero */ 

USHORT 

rc; 

fie return code ief 
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Query Active Font 


Assembler Language 

EXTRN DosPFSQueryAct: FAR 
INCL_DOSPFS EQU 1 


PUSH® 

ASCI IZ 

PrinterName 

PUSH® 

WORD 

CodePage 

PUSH® 

WORD 

FontID 

PUSH 

WORD 

SFN 

PUSH 

DWORD 

0 

CALL 

DosPFSQueryAct 


; Printer name string 
;Code Page return 
;Font ID return 
; System File Number 
; Reserved (must be zero) 


Returns WORD 
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DosPFSVerifyFont - 
Verify Font 


This call indicates whether the specified code page and font within that code page are available in the 
font file for the specified printer. 


DosPFSVerifyFont (PrfnterName, CodePage, FontID, Reserved) 


Parameters 

PrinterName ( PSZ ) - input 

Address of the name of the printer that queries the code page and font switching setup. 

CodePage ( USHORT) - input 

Code page to validate. Values are in the range 0 through 65535. 

FontID ( USHORT) - input 

Font ID to validate. Values are in the range 0 through 65535. A value of 0 indicates that any font 
within the specified code page is acceptable. 

Reserved ( ULONG ) - input 

Reserved must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are listed in the following section. 

Remarks 

DosPFSVerifyFont is intended for use only by applications that replace the spooler as a print monitor and 
that do code page switching. Other applications should use printer lOCTLs to manipulate printer code 
page switching. 

DosPFSVerifyFont is located in SPOOLCP.DLL (not in DOSCALLS.LIB) and requires an import statement 
in the module definition file. Refer to the IBM Operating System/2 Version 1.2 Building Programs, Module 
Definition File Statements section for information about the import statement. 

Return values are: 

2 Code page not available. 

4 Font ID not available. 

10 Invalid printer name as input. 

13 Received code page request when code page switcher not initialized. 

C Language 

# define INCL.DOSPFS 

USHORT rc = DosPFSVerifyFont (PrinterName, CodePage. FontID, Reserved); 


PSZ 

PrinterName; 

/* Printer name string */ 

USHORT 

CodePage; 

/* Code Page to validate */ 

USHORT 

FontID; 

/* Font Id to validate */ 

ULONG 

0; 

/* Reserved, set to zero */ 

USHORT 

rc; 

/•* return code */ 
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Verify Font 

Assembler Language 

EXTRN DosPFSVerifyFont: FAR 
INCL.DOSPFS EQU 1 

PUSH<a ASCI IZ Print erName ; Printer name string 

PUSH WORD CodePage ;Code Page to validate 

PUSH WORD FontID ;Font Id to validate 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosPFSVerifyFont 

Returns WORD 
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DosPhysicalDisk - 

Get Information about Partitionable Disk 


This call obtains information about partitionable disks. 


DosPhysicalDisk (Function, DataPtr, DataLen, ParmPtr, ParmLen) 

Parameters 

Function ( USHORT) - input 
The functions supported are: 

Value Definition 

1 Obtain total number of partitionable disks 

2 Obtain a handle to use with Category 9 lOCTLs 

3 Release a handle for a partitionable disk. 

DataPtr (PBYTE) - output 

Address of the buffer where the returned information is placed. 

DataLen ( USHORT) - input 

Length of the data buffer. The output data for each function is described below. 

Function DataLen Returned Information 

1 2 Total number of partitionable disks in the system, 1-based. 

2 2 Handle for the specified partitionable disk for the category 9 lOCTLs. 

3 0 None. Pointer must be zero. 

Note: All lengths are in bytes. 

ParmPtr (PBYTE) - input 

Address of the buffer used for input parameters. 

ParmLen (USHORT) - input 

Length of the parameter buffer. The input parameters required for each function are: 

Function ParmLen Input Parameters 

1 0 None. Must be set to zero. 

2 String length ASCIIZ string that specifies the partitionable disk. 

3 2 Handle obtained from function 2. 

Note: All lengths are in bytes. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERROR_INVALID_FUNCTION 

5 ERROR_ACCESS_DENIED 

6 ERROR JNVALIDJHANDLE 

33 ERROR_LOCK_VIOLATION 

87 ERROR JNVALID_PARAMETER 
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Remarks 

The ASCIIZ string used to specify the partitionable disk must be of the following format: 

number : <nu11 byte> 

Where: 

number specifies the partitionable disk (1-based) number in ASCII 

: must be present 

cnull byte> the byte of 0 for the ASCIIZ string 

The handle returned for the specified partitionable disk can only be used with the DosDevlOCt! call for the 
Category 9 Generic IOCTL. Use of the handle for a physical partitionable disk is not permitted for handle- 
based file system function calls, such as DosRead or DosClose. 

C Language 

#define INCLJJOSDEVICES 

USHORT rc = DosPhysi cal Disjunction, DataPtr, DataLen, ParmPtr, PannLen); 

USHORT Function; /* Type of information */ 

PBYTE DataPtr; /* Pointer to return buffer */ 

USHORT DataLen; /* Return buffer length */ 

PBYTE ParmPtr; /* Pointer to user-supplied information */ 

USHORT ParmLen; /* Length of user-supplied information */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosPhysicalDisk: FAR 
INCLJJOSDEVICES EQU 1 

PUSH WORD Function ;Type of information 

PUSH® OTHER DataPtr ; Return buffer (returned) 

PUSH WORD DataLen ; Return buffer length 

PUSHO OTHER ParmPtr ; User-supplied information 

PUSH WORD ParmLen ;Length of user-supplied information 

CALL DosPhysicalDisk 

Returns WORD 
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DosPortAccess - 
Request Port Access 


This call requests or releases access to ports for I/O privilege. 


DosPortAccess (Reserved, TypeOfAccess, FirstPort, LastPort) 

Parameters 

Reserved ( USHORT) - input 
Must be set to zero. 

TypeOfAccess ( USHORT) - input 

A request for or release of access to a port. 

Value Definition 

0 Request access 

1 Release access. 

FirstPort ( USHORT) - input 

Starting (low) number in a contiguous range or a single port. 

LastPort ( USHORT) - input 

Ending (high) number in a contiguous range or a single port. If only one port is being used, FirstPort 
and LastPort should both be set to this port. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO.ERROR 

5 ERROR_ACCESS_DENIED 

Remarks 

Note that CLI/STI privilege is also granted automatically. There is no need to make an additional call to 
DosCLI Access. 

Applications that perform I/O to port(s) in IOPL segments must request port access from the operating 
system. 

An application with no IOPL segments that accesses a device through a device driver or by an interface 
package such as VIO, does not need to issue this call. The device driver or interface package is respon- 
sible for obtaining the necessary I/O access. 

C Language 

#define 1NCL_D0SDEVICES 

USHORT rc = DosPortAccess (Reserved, TypeOfAccess, FirstPort, LastPort); 

USHORT 0; /* 0 */ 

USHORT TypeOfAccess; /* Request or release */ 

USHORT FirstPort; /* First port number */ 

USHORT LastPort; /* Last port number */ 

USHORT rc; /* return code */ 
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FAPI 


Assembler Language 

EXTRN Dos Port Access : FAR 
INCL_DO$DEVICES EQU 1 

PUSH WORD 0 {Reserved (must be zero) 

PUSH WORD TypeOf Access {Request or release 

PUSH WORD FirstPort {First port number 

PUSH WORD LastPort {Last port number 

CALL DosPortAccess 

Returns WORD 
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DosPtrace - 

Provides an Interface for Program Debugging 


This call provides an interface into the OS/2 kernel to facilitate program debugging. 


DosPtrace (PtraceB) 


Parameters 

PtraceB (PBYTE) - output 

Address of the Ptrace command/data buffer. This buffer is used to communicate between the debug 
program and the DosPtrace routines. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERRORJNVALID_FUNCTION 

5 ERROR_ACCESS_DENIED 

115 ERROR_PROTECTION_VIOLATION 

303 ERROR_INVALID_PROCID 

Remarks 

DosPtrace allows a parent process to control the execution of another process by implementing break- 
point debugging for a debugger. Both the program under test and the program being debugged must be 
executing in OS/2 mode. 

DosPtrace supports debugging of a process with multiple threads by allowing the debugger to read and 
write registers, freeze and resume thread execution, and get status on the threads. 

The debugger must be able to read and write the instructions, data, and registers of the program being 
debugged to insert breakpoint instructions. When a process runs in OS/2 mode, one process cannot 
directly manipulate the address space of another process. OS/2 controls this address space through the 
use of the trace flag facility in DosExecPgm and the Ptrace buffer in DosPtrace. 

The steps to program debugging in OS/2 mode follow: 

1. The debug program issues DosExecPgm for the program to be debugged, and specifies the trace 
option. 

2. The debug program calls DosPtrace with the TRC_C_Stop command to initialize the Ptrace Buffer. 

3. The debug program sets up a Ptrace buffer with commands for inserting the breakpoints and issues 
repeated DosPtrace requests as necessary. 

4. The debug program sets up a Ptrace buffer with a command to begin execution and issues 
DosPtrace. This may be a TRC_CS_Step, or TRC_C_Go. 

5. When the kernel DosPtrace program receives control from the program being debugged, it returns to 
the debug program with the Ptrace buffer set to the current register contents and with indicators of 
the reason for return. 

6. The kernel DosPtrace program receives control at a breakpoint interrupt, at processor exceptions, or 
when the program ends. 

To debug a process with multiple threads, set a field in the Ptrace buffer (Ptrace_B.TID) to the thread ID 
of the thread of interest. This causes the read/write register commands to receive only the register set of 
the specified thread. 

Note: For a process with multiple threads, the address space is the same for all the threads in the 

process. When commands are issued to read/write memory locations or set breakpoints, they 
affect all the threads in the process, even when a command is issued with a specific thread ID. 

The debugger may suspend and resume specific threads through use of the TRC_C_Freeze and 
TRC_C_Resume commands. Having only selected threads be affected by the breakpoints is useful for 
manipulating them while other threads are suspended. 
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Provides an Interface for Program Debugging 


When a process debugger terminates, the program being debugged also terminates. To accomplish this, 
an internal link between the debugger and the program being debugged is maintained. This link is estab- 
lished as a result of the first successful DosPtrace command. Once established, this link can not be 
reset. 

The process being debugged does not need to be a direct child process. In this situation, a small window 
of time exists between the DosExecPgm call and the first DosPtrace call. If the debugger terminates 
during this window, the program being debugged cannot be cleaned up. The system automatically termi- 
nates the program that was to be debugged. 

Specifying a trace option of 2 with DosStartSession enables a debugger running in the parent session to 
trace all processes associated with an application running in the child session, regardless of whether the 
process was started by DosStartSession request or by DosExecPgm. See DosStartSession for more 
information. 

Contents of the Ptrace Buffer: 


Ptrace_B 



Structure 

PID 

DW 

0 

; Process ID of the process being debugged 

TID 

DW 

0 

; Thread ID of the process being debugged 

Cmd 

DW 

0 

; Request to DosPtrace, or DosPtrace result code 

Value 

DW 

? 

; Data to DosPtrace, or DosPtrace error code 

OffV 

DW 

? 

; Offset value 

SegV 

DW 

? 

; Segment value 

MTE 

DW 

? 

; Library Module handle 

Ptrace B 
ENDS 





Exceptions: 


Ptraceregs 



Structure 

rAX 

DW 

? 

; Registers AX through SS 

rBX 

DW 

? 


rCX 

DW 

? 


rDX 

DW 

? 


rSI 

DW 

? 


rDI 

DW 

? 


rBP 

DW 

? 


rDS 

DW 

? 


rES 

DW 

? 


rIP 

DW 

? 


rCS 

DW 

? 


rF 

DW 

? 


rSP 

DW 

? 


rSS 

DW 

? 
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DosPtrace - 

Provides an Interface for Program Debugging 


Ptraceregs 



Structure 

Ptraceregs 

ENDS 

■ 

■ 



For the TRC_C_ReadMemB and TRC_C_WriteMemB commands, the remainder of the Ptrace buffer 
contains: 


Ptraceptr 



Structure 

OffB 

DW 

? 

; Buffer Address 

SegB 

DW 

? 


Ptraceptr 

ENDS 





DosPtrace Commands: PTraceJJ.Cmd must contain one of the following commands upon entrance to 
DosPtrace: 


TRC_C_Null 

EQUO 


; Invalid 

TRC_C_Read M em J 

EQU 1 


; Instruction 

TRC_C_Read M em_D 

EQU2 


; Data 

TRC_C_ReadMem 

EQU 

TRC_C_ReadMem_l 


TRC_C_ReadReg 

EQU 3 



TRC_C_W r ite M em J 

EQU 4 


; Instruction 

TRC_C_WriteMem_D 

EQU 5 


; Data 

TRC_C_W rite Mem 

EQU 

TRC_C_WriteMem_l 


TRC_C_W rite Reg 

EQU 6 



TRC_C_Go 

EQU 7 



TRC_C_Term 

EQU 8 



TRC_C_SStep 

EQU 9 



TRC_C_Stop 

EQU 10 


; Initialize 

TRC_C_Freeze 

EQU 11 



TRC_C_Resume 

EQU 12 



TRC_C_NumToSel 

EQU 13 



TRC_C_GetFPRegs 

EQU 14 



TRC_C_SetFPRegs 

EQU 15 



TRC_C_GetLibName 

EQU 16 



TRC_C_ThrdStat 

EQU 17 



T R C_C_R ead M e m_B 

EQU 18 


; Read Block 

TRC_C_WriteMem_B 

EQU 19 


; Write Block 
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DosPtrace - 

Provides an Interface for Program Debugging 


Commands and Required Input: A command is issued by placing the command number in Ptrace buffer, 
and calling DosPtrace with that buffer. 

All of the commands require that Ptrace_B.PID be the PID of the process to debug. 
TRC_C_Null Not a valid command 

Memory Operations: For the following commands, SegV:OffV is the affected location, and Ptrace_B. Value 
contains the value to write to or that was read from the debugger's memory. GDT segments 
cannot be written to: all except privilege level 2 and 3 access is disallowed. A write to a 
shared code segment makes that segment a non-shared segment before the write. 


TRC_C_ReadMemJ 

TRC_C_ReadMem_D 

TRCCReadMem 

TRC_c[wrlteMem_l 

TRC_C_WriteMem_D 

TRC C WriteMem 


Read instruction. 
Read data. 

Read any memory. 
Write instruction. 
Write data. 

Write to any memory. 


Block operations: For the block operations, SegV:OffV must point to the starting address in the 

debugger’s memory, and Value is the number of bytes to copy. On return, Value contains the 
number of bytes actually copied. 


TRC_C_ReadMem_B Read memory block. 
TRC_C_WriteMem_B Write memory block. 


Register / Thread Operations: For the following commands, Ptrace_B.TID must contain the thread ID of 
the thread in question. If the Ptrace_B.TID field is zero: 

• TRC_C_ThrdStat returns the number of threads in the process, (PTrace_B. Value). 

• TRC_C_Freeze and TRC_C_Resume affects ail of the debugger’s threads. 


TRC_C_ReadReg 

TRC_CWriteReg 

TRC_C_Freeze 

TRC_C_Resume 

TRC.CThrdStat 


Examine thread’s registers. 
Write thread’s registers. 
Suspend a thread. 

Resume a suspended thread. 
Get thread status. 


Command Operations: For the following commands, the Ptrace_B.PID must be valid. The Ptrace_B regis- 
ters are ignored for these commands. For TRC_C_Go and TRC_C_SStep, any thread may 
gain control first. The TRC_C_Term command terminates the program being debugged. 


TRCC.Go 

TRC_C_Term 

TRC_C_SStep 

TRC_C_Stop 


Run the program being debugged. 
Terminate the program being debugged. 
Run one instruction. 

Initialize PTrace buffer. 


Library Support: For TRC_C_NumToSel, PtraceJB.Value should be set to the segment number on 

entrance, and a valid selector on exit. Also, Ptrace_B.MTE should be set to the module’s 
handle. The MTE identifies the different library files in the program being debugged. 

For TRC_C_GetLibName, SegVrOffV should point to a buffer where the name of the library is 
returned. PTrace_B .Value should hold the library’s module handle (MTE). 

TRC_C_NumToSel Convert Segment number to selector. 

TRC_C_GetLibName Return name of module. 


Floating Point Support: For the following two commands, SegV:OffV must contain a pointer to a 94 byte 
buffer to be used to read/write the floating point registers from/to. 

The layout of this area is described in the NPX287 manual under the heading FSAVE/FRSTOR 
memory layout. 

TRC_C_GetFPRegs Read floating point registers. 

TRC_C_SetFPRegs Write floating point registers. 
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DosPtrace - 

Provides an Interlace for Program Debugging 

DosPtrace Return Codes: When DosPtrace returns to the debug program, the result is placed in 
Ptrace_B.Cmd, and reflects the reason for the return. 

The values returned are; 


TRC_C_SUC_ret 

EQUO 

; Success 

TRC_C_ERR_ret 

EQU -1 

; Error 

TRC.C_SIG.ret 

EQU -2 

; Signal 

TRC.C.TBT.ret 

EQU -3 

; Single Step 

TRC_C_BPT_ret 

EQU -4 

; Breakpoint 

TRC.C_NMI.ret 

EQU -5 

; Parity Error 

TRC.C_KIL.ret 

EQU -6 

; Process dying 

TRC_C.GPF.ret 

EQU -7 

; GP fault 

TRC.C.LIB.ret 

EQU -8 

; Library load 

TRC.C_FPE.ret 

EQU -9 

; FP error 

TRC.C_THD.ret 

EQU -10 

; Thread ending 

TRC.C.STP.ret 

EQU -11 

; Async. Stop. 


If Ptrace_B.Cmd is returned as TRC.C.ERR.ret, Ptrace_B. Value is set to one of the following: 

TRACE_BAD.COM M AN D EQU 1 

TR ACE.CH ILD.N OT_FOU ND EQU 2 

TRACECHILDUNTR ACE ABLE EQU 5 

If Ptrace.B.Cmd is returned as TRC.C.SIG.ret, the process is about to receive a signal. 

If Ptrace_B.Cmd is returned as TRC.C_KIL.ret, the process is about to terminate. 

If Ptrace_B.Cmd returns as TRC_C.GPF.ret, the process creates a General Protection fault. 
The fault type is returned in PTrace.B. Value, and SegV:OffV contains the reference that gen- 
erated the fault. 

If Ptrace_B.Cmd is returned as TRC.C.LIB.ret, a library module has been loaded. The new 
module table entry (MTE) is returned in Ptrace.B .Value. This can be used with the library 
support commands to identify the library module. The program module’s MTE is returned in 
PTrace_B.MTE. In this case, the initial TRC_C_Stop command should be re-issued until 
TRC_C_SUC_ret is returned. 

If Ptrace_B.Cmd is returned as TRC_C_FPE_ret, the process has generated a floating point 
error. 

If Ptrace_B.Cmd is returned as TRC.C.THD.ret, the Ptrace_b.TID field contains the thread ID 
of the terminating thread. 

If Ptrace.B.Cmd is returned as TRC.C.STP.ret, then the asynchronous stop caused the 
debugger to stop. 
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DosPtrace - 

Provides an Interface for Program Debugging 


C Language 

#define INCL_DOSQUEUES 
USHORT rc = DosPtrace (PtraceB) ; 

PBYTE PtraceB; /* Ptrace buffer (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosPtrace: FAR 
INCL_DO$QUEUES EQU 1 

PUSH® OTHER PtraceJJ ; Ptrace buffer (returned) 

CALL DosPtrace 

Returns WORD 
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DosPurgeQueue - 
Purge Queue 


This call purges a queue of all elements. 


DosPurgeQueue (QueueHandle) 


Parameters 

QueueHandle ( HQUEUE ) - input 
Handle of the queue to purge. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

330 ERROR_QUE_PROC_NOT_OWNED 

337 ERROR_QUE_INVALID_HANDLE 

Remarks 

A process that creates a queue with DosCreateQueue owns it. Only the owning process and any threads 
it creates can issue DosPurgeQueue to remove all the elements from the queue. 

C Language 

Idefine INCL.DOSQUEUES 

USHORT rc = DosPurgeQueue (QueueHandle) ; 

HQUEUE QueueHandle; /* Queue handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosPurgeQueue : FAR 
INCL_DOSQUEUES EQU 1 

PUSH WORD QueueHandle ; Queue handle 
CALL DosPurgeQueue 

Returns WORD 
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DosPutMessage - 

Output Message Text to Indicated Handle 


FAPI 


This call outputs the message in a buffer passed by a caller to the specified handle. The function formats 
the buffer to prevent words from wrapping if displayed to a screen. 


DosPutMessage (FlleHandle, MessageLength, MessageBuffer) 


Parameters 

FlleHandle (USHORT) - input 

Handle of the output file or device. 

MessageLength ( USHORT) - input 
Length of the message to be output. 

MessageBuffer ( PCHAR ) - input 

Address of the buffer that contains the returned message. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

1 9 ERROR.WRITE ^PROTECT 

321 ERROR_MRJJN_PERFORM 

Remarks 

Screen width is assumed to be 80 characters. The DosPutMessage call counts a CR/LF in the 80 charac- 
ters that it tries to write to the screen. If a word extends past column 78, it is put on the next line. 
DosPutMessage assumes the starting cursor position is column one when handling a word wrap. 

If the last character to be positioned on a line is a double-byte character that would be bisected, the rule 
above ensures that the character is not bisected. 


C Language 

Idefine INCL_D0SM1SC 


USHORT rc = DosPutMessage (Fi leHandle, MessageLength, MessageBuffer); 


USHORT 

USHORT 

PCHAR 


FileHandle; /* Handle of output file/device */ 
MessageLength; /* Length of message buffer */ 
MessageBuffer; /* Message buffer */ 


USHORT rc; 


/* return code */ 


Assembler Language 

EXTRN DosPutMessage: FAR 
INCL_D0SMISC EQU 1 


PUSH 

WORD 

FileHandle 

PUSH 

WORD 

MessageLength 

PU$H@ 

OTHER 

MessageBuffer 

CALL 

DosPutMessage 


;Handle of output file/device 
; Length of message buffer 
;Message buffer 


Returns WORD 
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DosQAppType - 
Return the Application Type 


This call returns the application type of an executable file. 


DosQAppType (ExecutableFileName, AppType) 


Parameters 

ExecutableFileName ( PSZ ) - input 

Address of the ASCIIZ string containing the filename of the executable file where the flags are 
returned. 

If the string appears to be a fully qualified path (contains a in the second position and/or contains 
a “\”) f only the indicated drive:di rectory is searched. If the string is not a fully qualified path, the 
current directory is searched. If the filename is not found in the current directory, each 
drive.directory specification in the PATH defined in the current program's environment is searched 
for this file. Note that any extension (.xxx) is acceptable for the executable filename. If no extension 
is specified, a default extension of ".exe" is used. AppType is a word that contains flags denoting the 
application type, as determined by reading the executable file header specified by 
ExecutableFileName. Note that the call sequence passes a pointer to a location in application 
memory to return the application type flags. 

AppType ( PUSHORT) - output 

Address of the application type defined as follows: 

Bit Description 

15-6 Reserved. 

5 Set to 1 if executable file is PC DOS format. Bits 0, 1 , 2, 3, and 4 are set to zero. 

4 Set to 1 if executable file is a dynamic link module. Bits 0, 1, 2, 3, and 5 are set to 0. 

3 Set to 1 if executable has been , ‘bound ,, (BIND command) as a Family API application. 

Bits 0, 1 and 2 still apply. 

2-0 Bits 2, 1 and 0 indicate application type, as specified in the header of the executable file. 

Value Definition 

000 Application type is not specified in executable header. 

001 Application is NOTWINDOWCOMPAT 

010 Application type is WINDOWCOMPAT 

011 Application type is WINDOWAPI 

rc {USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOT_FOUND 

3 ERROR_PATH_NOT_FOUND 

4 ERROR_TOO_MANY_OPEN_FILES 

11 ERROR_BAD_FORMAT 

15 ERRORJNVALID__DRIVE 

32 ERROR_SHARING_VIOLATION 

108 ERROR_DRIVE_LOCKED 

110 ERROR_OPEN_FAILED 

191 ERR0RJNVALID_EXE_S1GNATURE 

192 ERROR_EXE_MARKEDJNVALID 

Remarks 

This function is used by the Presentation Manager shell to determine the application type being executed. 
The application type is specified at link time in the module definition file. 
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DosQAppType - 
Return the Application Type 


C Language 

^define INCL_DOSSESMGR 

USHORT rc = DosQAppType (ExecutableFileName, AppType); 

PSZ ExecutableFileName; /* Address of executable file path name string */ 

PUSHORT AppType; /* Address to put application type flags */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQAppType : FAR 
INCL_DO$SESMGR EQU 1 

PUSH® ASCI IZ ExecutableFileName Executable file path name string 
PUSH® WORD AppType; ;Appli cation type flags (returned) 

CALL DosQAppType 

Returns WORD 
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FAPI 


DosQCurDir - 
Query Current Directory 


This call returns the full path name of the current directory for the requesting process for the specified 
drive. 


DosQCurDir (DriveNumber, DirPath, DirPathLen) 


Parameters 

DriveNumber (USHORT) - input 
Drive number, for example: 

Value Definition 

0 default 

1 A 

2 B 


DirPath (PBYTE) - output 

Address of the fully qualified path name of current directory. 

DirPathLen ( PUSHORT) - Input/output 

Address of the length of the DirPath buffer. On input, this field contains the length of the directory 
path buffer in bytes. On output, if an error is returned because the buffer is too small, this field con- 
tains the required length. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

15 ERROR JNVALID_DRIVE 

26 ERROR_NOT_DOS_DISK 

108 ERROR_DRIVE_LOCKED 

111 ERROR_BUFFER_OVERFLOW 

Remarks 

The drive letter is not part of the returned string. The string does not begin with a backslash and is termi- 
nated by a byte containing 00H. 

The system returns the length of the returned DirPath string in DirPathLen, which does not include the 
terminating null byte. In the case where the DirPath buffer is of insufficient length to hold the current 
directory path string, the system returns the required length (in bytes) for DirPath in DirPathLen. 

For FSDs, the case of the current directory is set according to the DirName passed in, not according to 
the case of the directories on disk. For example, if the directory “c:\bin” is created and DosChDir is 
called with DirName ,, c:\bin M , the current directory returned by DosQCurDir will be "c:\bin". 

Programs running without the NEWFILES bit set are allowed to DosChDir to a non-8.3 filename format 
directory. 

DosQSysInfo must be used by an application to determine the maximum path length supported by OS/2. 
The returned value should be used to dynamically allocate buffers that are to be used to store paths. 
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DosQCurDir - 
Query Current Directory 


FAPI 


C Language 

^define INCL_DOSFILEMGR 

USHORT rc = DosQCurDir (Dri veNumber, DirPath, DirPathLen); 

USHORT DriveNumber; /* Drive number */ 

PBYTE DirPath; /* Directory path buffer (returned) */ 

PUSHORT DirPathLen; /* Directory path buffer length (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQCurDir: FAR 
INCLJMSFILEMGR EQU 1 

PUSH WORD DriveNumber ;Drive number 

PUSHO OTHER DirPath ;Di rectory path buffer (returned) 

PUSH® WORD DirPathLen ;Di rectory path buffer length (returned) 

CALL DosQCurDir 

Returns WORD 
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FAPI 


DosQCurDisk - 
Query Current Disk 


This call determines the current default drive for the requesting process. 


DosQCurDisk (DriveNumber, LoglcalDriveMap) 


Parameters 

DriveNumber ( PUSHORT) - output 

Address of the number of the default drive, for example: 

Value Definition 

1 A 

2 B 


LoglcalDriveMap (PULONG) - output 

Address of the bit map (stored in the low-order portion of the 32-bit, doubleword area) where the 
system returns the mapping of the logical drives. Logical Drives A to Z have a one-to-one mapping 
with the bit positions 0 to 25 of the map; for example, bit 0 is drive A, bit 1 is drive B, and so forth. 
The settings of these bits indicate which drives exist: 

Value Definition 

0 The logical drive does not exist. 

1 The logical drive exists. 

rc (USHORT) - return 

Return code description is: 

0 NO_ERROR 

C Language 

#define INCL_DOSFILEMGR 

USHORT rc = DosQCurDisk (DriveNumber, LogicalDriveMap); 

PUSHORT DriveNumber; /* Default drive number (returned) */ 

PULONG LogicalDriveMap; /* Drive map area (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQCurDisk: FAR 
INCL_DOSFILEMGR EQU 1 

PUSH® WORD DriveNumber ;Default drive number (returned) 

PUSH® DWORD LogicalDriveMap ; Drive map area (returned) 

CALL DosQCurDisk 

Returns WORD 
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DosQFHandState - 
Query File Handle State 


FAPI 


This call queries the state of the specified file. 


DosQFHandState (FlleHandle, FlleHandleState) 


Parameters 

FileHandle ( HFILE ) - input 

Handle of the file to be queried. 

FHeHand leState ( PUSHORT) — output 

Address of the contents of the open mode word defined in a previous DosOpen or DosOpen2 call. 

Bit Description 

15 Direct Open flag: 

0 = PathName represents a file to be opened in the normal way. 

1 = PathName is “Drive:” and represents a mounted disk or diskette volume to be 
opened for direct access. 

14 Write-Through flag: 

0 = Writes to the file may be run through the file system buffer cache. 

1 = Writes to the file may go through the file system buffer cache but the sectors are 
written (actual file I/O completed) before a synchronous write call returns. This state of 
the file defines it as a synchronous file. For synchronous files, this is a mandatory bit in 
that the data must be written out to the medium for synchronous write operations. 

This bit is not inherited by child processes. 

13 Fail-Errors flag. Media I/O errors are handled as follows: 

0 = Reported through the system critical error handler. 

1 = Reported directly to the caller by return code. 

Media I/O errors generated through an IOCTL Category 8 function always get reported 
directly to the caller by return code. The Fail-Errors function applies only to non-IOCTL 
handle-based file I/O calls. 

This bit is not inherited by child processes. 

12 No-Cache/Cache: 

0 = It is advisable for the disk driver to cache the data in I/O operations on this file. 

1 = I/O to the file need not be done through the disk driver cache. 

This bit is an advisory bit, and is used to advise FSDs and device drivers on whether it is 
worth caching the data. This bit, like the write-through bit, is a per-handie bit. 

This bit is not inherited by child processes. 

11-8 Reserved Bits. 

7 Inheritance flag: 

0 = File handle is inherited by a spawned process resulting from a DosExecPgm call. 

1 = File handle is private to the current process. 

This bit is not inherited by child processes. 
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FAPI 


DosQFHandState - 
Query File Handle State 


6 -4 Sharing Mode flags: The file sharing mode flags define what operations other processes 

may perform on the file shown as follows: 

Value Definition 

001 Deny Read/Write access 

010 Deny Write access 

011 Deny Read access 

100 Deny neither Read or Write access (Deny None). 

Any other value is invalid. 

3 Reserved Bit. 

2 — 0 Access Mode flags. The file access is assigned as follows: 

Value Definition 

000 Read-Only access 

001 Write-Only access 

010 Read/Write access. 

Any other value is invalid. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERRORJNVALIDJHANDLE 

Remarks 

When a critical error occurs that the application cannot handle, it may reset critical error handling to be 
performed by the system. This is done by calling DosSetFHandState to turn off the fail/errors bit and then 
reissuing the I/O call. The expected critical error reoccurs, and control is passed to the system critical 
error handler. The precise time that the effect of this function is visible at the application level is unpre- 
dictable when asynchronous I/O is pending. 

The DASD Open bit parameter is the “Direct I/O flag.” It provides an access mechanism to a disk or 
diskette volume independent of the file system. This mode should only be used by systems programs 
and not by application programs. 

Named Pipe Considerations 

As defined by OS/2 D = 0. Other bits as defined by DosMakeNmPipe (serving end), DosOpen (client end), 
or the last DosSetFHandState. 

C Language 

/define INCL_DOSFILEMGR 

USK0RT rc = DosQFHandState(FileHandle, FileHandl estate); 

HFILE FileHandle; /* File handle */ 

PUSH0RT FileHandl estate; /* File handle state (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQFHandState: FAR 
INCL.DOSFILEMGR EQU 1 

PUSH WORD FileHandle ;File handle 

PUSH@ WORD FileHandl estate ; Fi 1 e handle state (returned) 

CALL DosQFHandState 

Returns WORD 
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DosQFilelnfo — 

Query File Information 


FAPI 


This call returns information for a specific file. 


DosQFilelnfo (FileHandle, FllelnfoLevel, FilelnfoBuf, FllelnfoBufSize) 


Parameters 

FlleHandle (HFILE) - input 
File handle. 

FllelnfoLevel (USHORT) - input 

Level of file information required. A value of 1, 2, or 3 can be specified. Level 4 is reserved. The 
structures described in FilelnfoBuf indicate the information returned for each of these levels. 

FllelnfoBuf (PBYTE) - output 

Address of the storage area where the system returns the requested level of file information. File 
information, where applicable, is at least as accurate as the most recent DosClose, DosBufReset, 
DosSetFilelnfo, or DosSetPathlnfo. 

Level 1 Information 

FilelnfoBuf contains the following structure, to which file information is returned: 
filedate ( FDATE ) 

Structure containing the date of file creation. 

Bit Description 

15-9 Year, in binary, of file creation 
8-5 Month, in binary, of file creation 

4-0 Day, in binary, of file creation. 

filetime ( FTIME ) 

Structure containing the time of file creation. 

Bit Description 

15-11 Hours, in binary, of file creation 

10-5 Minutes, in binary, of file creation 

4-0 Seconds, in binary number of two-second increments, of file creation, 

fileaccessdate (FDATE) 

Structure containing the date of last access. See FDATE in filedate. 
fileaccesstime (FTIME) 

Structure containing the time of last access. See FTIME in filetime, 
writeaccessdate (FDATE) 

Structure containing the date of last write. See FDATE in filedate. 
wrfteaccesstlme (FTIME) 

Structure containing the time of last write. See FTIME in filetime. 

filesize (ULONG) 

File size. 

filealloc (ULONG) 

Allocated file size. 

flleattrlb (USHORT) 

Attributes of the file, defined in DosSetFileMode. 

Level 2 Information 

FilelnfoBuf contains a structure similar to the Level 1 structure, with the addition of the cbList 
field after the fileattrib field. 


2-250 Control Program Programming Reference 







FAPI 


DosQFilelnfo - 
Query File Information 


cbList ( ULONG ) 

On output, this field contains the length of the entire EA set for the file object. This value 
can be used to calculate the size of the buffer required to hold EA information returned 
when FilelnfoLevel = 3 is specified. 

Level 3 Information 

FilelnfoBuf contains an EAOP structure, which has the following format: 
fpGEAList (PGEAUST) 

Address of GEAList. GEAList is a packed array of variable length “get EA” structures, each 
containing an EA name and the length of the name. 

fpFEAList (PFEALIST) 

Address of FEAList. FEAList is a packed array of variable length “full EA” structures, each 
containing an EA name and its corresponding value, as well as the lengths of the name and 
the value. 

oError (ULONG) 

Offset into structure where error has occurred. 

On input, FilelnfoBuf is an EAOP structure. fpGEAList points to a GEA list defining the attribute 
names whose values are returned. fpFEAList points to a data area where the relevant FEA list is 
returned. The length field of this FEA list is valid, giving the size of the FEA list buffer. oError 
points to the offending GEA entry in case of error. Following is the format of the GEAList 
structure: 

cbList (ULONG) 

Length of the GEA list, including the length itself, 
list (GEA) 

List of GEA structures. A GEA structure has the following format: 
cbName (BYTE) 

Length of EA ASCII2 name, which does not include the null character. 

szName (CHAR) 

ASCIIZ name of EA. 

On output, FilelnfoBuf is unchanged. The buffer pointed to by fpFEAList is filled in with the 
returned information. If the buffer fpFEAList points to isn't large enough to hold the returned 
information (ERROR_BUFFER_OVERFLOW) cbList is still valid, assuming there's at least enough 
space for it. Its value is the size of the entire EA set for the file, even though only a subset of 
attributes was requested. Following is the format of the FEAList structure: 

cbList (ULONG) 

Length of the FEA list, including the length itself, 
list (FEA) 

List of FEA structures. An FEA structure has the following format: 

Flags (BYTE) 

Bit indicator describing the characteristics of the EA being defined. 

Bit Description 

15 Critical EA. 

14-0 Reserved and must be set to zero. 

If bit 15 is set to 1, this indicates a critical EA. If bit 15 is 0, this means the EA is noncrit- 
ical; that is, the EA is not essential to the intended use by an application of the file with 
which it is associated. 

cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character. 
cbValue (USHORT) 

Length of EA value, which cannot exceed 64KB. 
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Query File Information 


FAPI 


szName (PSZ) 

Address of the ASCIIZ name of EA. 
aValue (PSZ) 

Address of the free-format value of EA. 

Note: The szName and aValue fields are not included as part of header or include files. 
Because of their variable lengths, these entries must be built manually. 

FilelnfoBufSIze ( USHORT) - output 
Length of FilelnfoBuf. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

5 ERROR_ACCESS_DENIED 

6 ERRORJNVALID_HANDLE 

111 ERROR_BUFFER_OVERFLOW 

124 ERRORJNVALIDJ.EVEL 

130 ERROR_DIRECT_ACCESS_HANDLE 

254 ERROR_INVALID_EA_NAME 

255 E R ROR JE A _L 1ST _l NCONSISTENT 


Remarks 

The FAT file system supports modification of only date and time information contained in file information 
level 1. Zero is returned for the creation and access dates and times. 


To return information contained in any of the file information levels, DosQFilelnfo has to be able to read 
the open file. DosQFilelnfo works only when the file is opened for read access, with a deny-write sharing 
mode specified for access by other processes. If the file is already opened by another process that has 
specified conflicting sharing and access modes, a call to DosOpen or DosOpen2 fails. 

DosEnum Attribute returns the lengths of EAs. This information can be used to calculate the size of 
FilelnfoBuf needed to hold full extended attribute (FEA) information returned by DosQFilelnfo when Level 
3 is specified. The size of the buffer is calculated as follows: 

One byte {for fea_usFlags) 4* 

One byte (for fea_cbName) + 

Two bytes (for fea_cbValue) + 

Value of cbName (for the name of the EA) + 

One byte (for terminating NULL in fea_cbName) + 

Value of cbValue (for the value of the EA) 


C Language 


typedef struct _l 

FDATE { 

/* 

unsigned day 

: 5; 

/* 

unsigned month 

: 4; 

/* 

unsigned year 

: 7; 

/* 


fdate */ 

binary day for directory entry */ 
binary month for directory entry */ 
binary year for directory entry */ 


} FDATE; 


typedef struct _FTIME { 

unsigned twosecs : 5; 
unsigned minutes : 6; 
unsigned hours : 5; 

} FUME; 


/* ftime */ 

/* binary number of two-second increments */ 
/* binary number of minutes */ 

/* binary number of hours */ 
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DosQFilelnfo - 
Query File Information 


typedef struct _FILESTATUS { /* fsts */ 

FDATE fdateCreation; /* date of file creation */ 

FT I ME ftimeCreation; /* time of file creation */ 

FDATE fdateLastAccess; /* date of last access */ 

FTIME ftimeLastAccess; /* time of last access */ 

FDATE fdateLastWrite; /* date of last write */ 

FTIME ftimeLastWrite; /is time of last write */ 

ULONG cbFile; /is file size (end of data) is/ 

ULONG cbFileAlloc; /* file allocated size */ 

USHORT attrFile; /is attributes of the file is/ 

} FILESTATUS; 

typedef struct _GEA { /* gea */ 

BYTE cbName; /is name length not including NULL is/ 

CHAR szName[l]; /is attribute name is/ 

} GEA; 

typedef struct _GEALI$T { /is geal is/ 

ULONG cbList; /is total bytes of structure including full list is/ 

GEA list [1] ; /* variable length GEA structures is/ 

} GEALIST; 

typedef struct _FEA { /* fea */ 

BYTE fEA; /is flags is/ 

BYTE cbName; /* name length not including NULL */ 

USHORT cbValue; /is value length */ 

} FEA; 

typedef struct _FEALIST { /* feal */ 

ULONG cbList; /* total bytes of structure including full list */ 

FEA list [1] ; /is variable length FEA structures is/ 

} FEAL I ST; 

typedef struct _EA0P { /* eaop */ 

PGEALIST fpGEAList; /is general EA list is/ 

PFEALIST fpFEAList; /is full EA list is/ 

ULONG oError; 

> EAOP; 

Idefine INCL_DOSFILEMGR 

USHORT rc = DosQFileInfo(FileHandle # FilelnfoLevel , FilelnfoBuf, 

FilelnfoBufSize); 

HFILE FileHandle; /* File handle */ 

USHORT FilelnfoLevel; /* File data required */ 

PBYTE FilelnfoBuf; /is File data buffer (returned) */ 

USHORT FilelnfoBufSize; /* File data buffer size is/ 

USHORT rc; /is return code */ 

Assembler Language 
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FAPI 


FDATE st rue 
fdate_fs dw ? 

FDATE ends 
FTIME struc 
ftime_fs dw ? 

FTIME ends 
FILESTATUS struc 

fsts_fdateCreation dw (size FDATE) /2 dup (?) ;date of file creation 

fstsJ'timeCreation dw (size FTIME)/2 dup (?) ;time of file creation 

fsts_fdateLastAccess dw (size FDATE) /2 dup (?) ;date of last access 

fsts_ftimeLastAccess dw (size FTIME)/2 dup (?) ;time of last access 

fsts_fdateLastWrite dw (size FDATE) /2 dup (?) ;date of last write 

f$t$_ftimeLastWrite dw (size FTIME) /2 dup (?) ;time of last write 

fsts_cbFile dd ? ; f i 1 e size (end of data) 

fsts_cbFileAlloc dd ? ;f i 1 e allocated size 

fsts_attrFi1e dw ? -.attributes of the file 

FILESTATUS ends 
GEA struc 

gea_cbName db ? ;name length not including NULL 

gea_szName db 1 dup (?) ; attribute name 

GEA ends 

GEALIST struc 

geal_cbList dd ? ; total bytes of structure including full list 

gealjist db size GEA * 1 dup (?) ; variable length GEA structures 

GEALIST ends 

FEA struc 

fea_fEA db ? ; flags 

fea_cbNarae db ? ;name length not including NULL 
fea_cbValue dw ? ; value length 

FEA ends 

FEALIST struc 

feal_cbList dd ? ; total bytes of structure including full list 

fealjist db size FEA * 1 dup (?) variable length FEA structures 

FEALIST ends 

EAOP struc 

eaop_f pGEALi st dd ? ; general EA list 
eaop_fpFEAList dd ? ; f ul 1 EA list 

eaop_oError dd ? ; 

EAOP ends 

EXTRN DosQFilelnfo: FAR 
INCLJ)OSFILEMGR EQU 1 

PUSH WORD FileHandle ;File handle 

PUSH WORD FilelnfoLevel ;File data required 

PUSH8 OTHER FilelnfoBuf ;File data buffer (returned) 

PUSH WORD FilelnfoBuf Size ;File data buffer size 

CALL DosQFilelnfo 

Returns WORD 
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Query File Mode 


This call queries the mode (attribute) of the specified file. 


DosQFileMode (FilePathName, CurrentAttribute, Reserved) 


Parameters 

FilePathName (PSZ) - input 

Address of the file path name. 

DosQSysInfo is called by an application during initialization to determine the maximum path length 
allowed by OS/2. 

CurrentAttribute (PUSHORT) - output 
Address of the file’s current attribute. 

Bit Description 

15-6 Reserved. 

5 File archive 

4 Subdirectory 

3 Reserved. 

2 System file 

1 Hidden file 

0 Read only file 

These bits can be set individually or in combination. For example, an attribute value of 0021 H (bits 5 
and 0 set to 1) indicates a read-only file that is archived. 

Reserved (ULONG) - input 

Reserved must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FILE_NOT_FOUND 

3 E R RO R_P ATH_N OT_FOU N D 

26 ERROR JMOTJOOSJDISK 

87 ERROR_INVALID_PARAMETER 

108 ERROR_DRIVE_LOCKED 

206 ERROR_FILENAME_EXCED_RANGE 

Remarks 

The ‘Volume Label' type attribute is not returned by DosQFileMode. DosQFSInfo may be used for this 
purpose. 

C Language 

#def i ne INCL_DOSFILEMGR 

USHORT rc = DosQFileMode(Fi lePathName, CurrentAttribute* Reserved) ; 

PSZ FilePathName; /* File path name */ 

PUSHORT CurrentAttribute; /* Data area (returned) */ 

ULONG 0; /* Reserved (must be zero) */ 

USHORT rc; /* return code */ 
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DosQFileMode - fapi 

Query File Mode 


Assembler Language 

EXTRN DosQFileMode: FAR 

INCL_DO$FILEMGR EQU 1 

PUSH® ASCI IZ FilePathName ;Fi1e path name 

PUSH® WORD CurrentAttri bute ;Data area (returned) 

PUSH DWORD 0 Reserved (must be zero) 

CALL DosQFileMode 

Returns WORD 
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DosQFSAttach - 
Query Attached FSD Information 


Query information about an attached file system (local or remote), or about a character device or pseudo- 
character device attached to the file system. 


DosQFSAttach (DeviceName, Ordinal, FSAInfoLevel, DataBuffer, DataBufferLen, Reserved) 


Parameters 

DeviceName (PSZ) - input 

Address of a drive letter or the name of a character or pseudo-character device. If DeviceName is a 
drive, it is an ASCIIZ string having the form of drive letter followed by a colon. If DeviceName is a 
character or pseudo-character device name, its format is that of an ASCIIZ string in the format of an 
OS/2 file name in a subdirectory called \DEV\. This parameter is ignored if level 2 or 3 is specified 
for FSAInfoLevel. 

Ordinal (USHORT) - output 

Index into the list of character or pseudo-character devices, or the set of drives. Ordinal always 
starts at 1. The Ordinal position of an item in a list has no significance at all. Ordinal is used strictly 
to step through the list. The mapping from Ordinal to item is volatile and may change from one call 
to DosQFSAttach to the next. This parameter is ignored if level 1 is specified for FSAInfoLevel. 

FSAInfoLevel ( USHORT) - input 

Level of information returned in DataBuffer: 

• Level 0001 H returns data for the specific drive or device name referred to by DeviceName. The 
Ordinal field is ignored. 

• Level 0002 H returns data for the entry in the list of character or pseudo-character devices 
selected by Ordinal. The DeviceName field is ignored. 

• Level 0003H returns data for the entry In the list of drives selected by Ordinal. The DeviceName 
field is ignored. 

DataBuffer (PBYTE) - output 

Address of the return information buffer, has the following format: 

IType ( USHORT) 

Type of item. 

Value Definition 

1 Resident character device 

2 Pseudo-character device 

3 Local drive 

4 Remote drive attached to FSD. 

cbName ( USHORT) 

Length of item name, not counting null. 

szName ( UCHAR ) 

Item name, ASCIIZ string. 

cbFSDName (USHORT) 

Length of FSD name, not counting null. 

szFSDName (UCHAR) 

Name of FSD item is attached to, ASCIIZ string. 

cbFSAData ( USHORT) 

Length of FSD Attach data returned by FSD. 
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DosQFSAttach - 

Query Attached FSD Information 


rgFSAData (UCHAR) 

FSD Attach data returned by FSD. 

Note: The szFSDName Is the FSD name exported by the FSD, which is not necessarily the same as 
the FSD name in the boot sector. 

For local character devices (iType =1), cbFSDName = 0 and szFSDName contains only a termi- 
nating NULL byte, and cbFSAData = 0. 

For local drives (iType = 3), szFSDName contains the name of the FSD attached to the drive at the 
time of the call. This information changes dynamically. If the drive is attached to the kernel's resi- 
dent file system, szFSDName contains FAT or unknown. Since the resident file system gets attached 
to any disk that other FSDs refuse to mount, it is possible to have a disk that does not contain a 
recognizable file system, but yet gets attached to the resident file system. In this case, it is possible 
to detect the difference, and this information would help programs in not destroying data on a disk 
that was not properly recognized. 

DataBufferLen ( PUSHORT) - output 

Address of the byte length of the return buffer. Upon return, it is the length of the data returned in 
DataBuffer by the FSD. 

Reserved ( ULONG ) - input 

Reserved, must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

15 ERROR_INVAL!D_DRIVE 

1 1 1 ERRORBUFFEROVERFLOW 

124 ERROR JNVALIDJ.EVEL 

259 ERROR_NO_MORE_ITEMS 

Remarks 

Information about all block devices and all character and pseudo-character devices is returned by this 
call. 

The information returned by this call is highly volatile. Calling programs should be aware that the 
returned information may have already changed by the time it's returned to them. 

The information returned for disks that are attached to the kernel's resident file system can be used to 
determine if the kernel definitely recognized the disk as one with its file system on it, or if the kernel just 
attached its file system to it because no other FSDs mounted the disk. This can be important information 
for a program that needs to know what file system is attached to the drive. It is quite easy to get into a 
situation where the FSD that recognizes a certain disk has not been installed into the system. In such a 
case, there is a potential for the data on the disk to be destroyed since the wrong file system is attached 
to the disk by default. 

C Language 

fdefine 1NCL_D0SFILEMGR 

USHORT rc * OosQFSAttach(DeviceName, Ordinal, FSAInfoLevel , DataBuffer, DataBufferLen, 0); 


PSZ 

DeviceName; 

/* 

Device name or drive letter string 

*/ 

USHORT 

Ordinal ; 

/* 

Ordinal of entry in name list */ 


USHORT 

FSAInfoLevel ; 

/* 

Type of attached FSD data required 

*/ 

PBYTE 

DataBuffer; 

/* 

Returned data buffer */ 


PUSHORT 

DataBufferLen; 

/* 

Buffer length */ 


ULONG 

0; 

/* 

Reserved (must be zero) */ 


USHORT 

rc; 

/* 

return code */ 
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Query Attached FSD Information 

Assembler Language 

EXTRN DosQFSAttach: FAR 
INCLJ30SFILEMGR EQU 1 

PUSH® ASCI 12 DeviceName ; Device name or drive letter string 

PUSH WORD Ordinal ;0rdinal of entry in name list 

PUSH WORD FSAInfoLevel ;Type of attached FSD data required 

PUSH® OTHER DataBuffer ;Data buffer (returned) 

PUSH® WORD DataBufferLen ; Buffer length (returned) 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosQFSAttach 

Returns WORD 
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Query File System Information 


FAPI 


This call queries information from a file system device. 


DosQFSInfo (DriveNumber, FSInfoLevel, FSInfoBuf, FSInfoBufSize) 


Parameters 

DriveNumber ( USHORT) - input 

Logical drive number (0 = default, 1 = A, and so on). 

When a logical drive is specified, the media in the drive is examined (local drive only) and the 
request is passed to the FSD responsible for managing that media or to the FSD that is attached to 
the drive. 

FSInfoLevel ( USHORT) - input 

Level of file information required. 

FSInfoBuf (PBYTE) - output 

Address of the storage area where the system returns the requested level of file information. 

Level 1 Information 

For FSInfoLevel = 1, Information is returned in the following structure: 

filesysid ( ULONG ) 

File system ID. 

sectornum (ULONG) 

Number of sectors per allocation unit. 

unitnum (ULONG) 

Number of allocation units. 

unitavail (ULONG) 

Number of allocation units available. 

bytesnum (USHORT) 

Number of bytes per sector. 

Level 2 Information 

For FSInfoLevel = 2, the information is returned in the following format: 

reserved (ULONG) 

Reserved 

volumelength (BYTE) 

Length of the volume label, not including the null. 

volumelabel (CHAR) 

Volume label ASCIIZ string. 

FSInfoBufSize ( USHORT) 

Length of the buffer. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

15 ERROR_INVALID_DRIVE 

111 ERROR_BUFFER_OVERFLOW 

124 ERRORJNVALIDJ.EVEL 

125 ERROR_NO_VOLUME_LABEL 
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Query File System Information 

Remarks 

Trailing blanks supplied at volume label definition time are not considered to be part of the label and are 
therefore not returned as valid label data. Volume label is limited to a length of 11 bytes. 

Volume Serial Number is a unique 32-bit number used by OS/2 to positively identify its disk/diskette 
volumes. The hard error prompts the user for an unmounted removable volume by displaying both the 
Volume Serial Number (as an 8 digit hexadecimal number) and the Volume Label. 

If there is no volume serial number on the disk/diskette, the volume serial number information is returned 
as binary zeros. If there is no volume label on the disk/diskette, the volume label information is returned 
as blank spaces. If there is no volume serial number and/or volume label for disk/diskette volumes for- 
matted by DOS 3.X t this information is not displayed by the Hard Error Handler. 

C Language 

typedef struct _FSALLOCATE { 

ULONG idFiTeSystem; /* file system ID */ 

ULONG cSectorUnit; /* number sectors per allocation unit */ 

ULONG cUnit; /* number of allocation units */ 

ULONG cUnitAvail; /* available allocation units */ 

USHORT cbSector; /* bytes per sector */ 

} FS ALLOCATE; 

typedef struct _FDATE { /* fdate */ 

unsigned day : 5; /* binary day for directory entry */ 

unsigned month ; 4; /* binary month for directory entry */ 

unsigned year : 7; /* binary year for directory entry */ 

} FDATE; 

typedef struct _FTIME { /* ftitne */ 

unsigned twosecs : 5; /* binary number of two-second increments */ 

unsigned minutes : 6; /* binary number of minutes */ 

unsigned hours : 5; /* binary number of hours */ 

} FTIME; 

typedef struct _FSINF0 { /* fsinf */ 

FDATE fdateCreation; 

FTIME ftimeCreation; 

VOLUMELABEL vol; 

} FSINFO; 

typedef struct VOLUMELABEL { /* vol */ 

BYTE cch; 

CHAR szVol Label [12]; 

} VOLUMELABEL; 

#define INCL.DOSFILEMGR 

USHORT rc = DosQFSInfo(Dri veNumber, FSInfoLevel » FSInfoBuf. FSInfoBufSize) ; 

USHORT Dri veNumber; /* Drive number */ 

USHORT FSInfoLevel; /* File system data required */ 

PBYTE FSInfoBuf ; fie File system info buffer */ 

USHORT FSInfoBufSize; /* File system info buffer size */ 

USHORT rc; /* return code */ 
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Query File System Information 


FAPI 


Assembler Language 

FSALLOCATE struc 


f sal 1 ocj dFi 1 eSystem 

dd 

? 

f sal 1 oc_cSectorUni t 

dd 

7 

fsalloc_cUnit 

dd 

? 

fsalloc_cUnitAvail 

dd 

? 

fsalloc cbSector 

dw 

? 


FSALLOCATE ends 

EXTRN DosQFSInfo: FAR 
INCLJOSFILEMGR EQU 1 

PUSH WORD DriveNumber ; Drive number 

PUSH WORD FSInfoLevel ;File system data required 

PUSH® OTHER FSInfoBuf ; Fi 1 e system info buffer (returned) 

PUSH WORD FSInfoBufSize ; Fi 1 e system info buffer size 

CALL DosQFSInfo 

Returns WORD 
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DosQHandType - 
Query Handle Type 


This call determines whether a handle references a file or a device. 


DosQHandType (FileHandle, HandType, FlagWord) 


Parameters 

FileHandle ( HFILE ) - Input 
File handle. 

HandType (PUSHORT) - output 

Address of the value Indicating the handle type. HandType is composed of two bytes: 

Bit Description 

15 Network bit: 

0 = The handle refers to a local file, device, or pipe. 

1 = Means that the handle refers to a remote file, device, or pipe. 

14—8 Reserved. 

7-0 HandleClass describes the handle class. It may take on the following values in the low 

byte of HandleType: 

Value Definition 

0 Handle is for a disk file 

1 Handle is for a character device 

2 Handle is for a pipe. 

Values greater than 2 are reserved. 

FlagWord (PUSHORT) - output 

Address of the device driver's attribute word if HandleType indicates a local character device. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

Remarks 

This function allows programs that are interactive or file-oriented to determine the source of their input. 
For example, CMD.EXE suppresses writing prompts if the input is from a disk file. 


C Language 

#define INCL_DO$FILEMGR 


USHORT rc 

= DosQHandType(FileHandle, HandType, FlagWord); 

HFILE 

FileHandle; 

/* File handle */ 

PUSHORT 

HandType; 

/* Handle type (returned) */ 

PUSHORT 

FlagWord; 

/* Device driver attribute (returned) */ 

USHORT 

rc; 

/* return code */ 
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DosQHandType - 
Query Handle Type 


FAPI 


Assembler Language 

EXTRN DosQHandType: FAR 
INODOSFILEMGR EQU 1 

PUSH WORD FileHandle ;F11e handle 

PUSH® WORD HandType ;Handle type (returned) 

PUSH® WORD FlagWord ;Device driver attribute (returned) 

CALL DosQHandType 

Returns WORD 
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DosQNmPHandState - 
Query Named Pipe State 


This call returns information for a named pipe's specific handle state. 


DosQNmPHandState (Handle, PIpeHandleState) 


Parameters 

Handle (HPIPE) - input 

Handle of the named pipe returned by DosMakeNmPipe or DosOpen. 

PIpeHandleState (PUSHORT) - output 

Address of the named pipe handle state: 

Bit Description 

15 Blocking; pipe is defined as follows: 

0 = Reads/Writes block if no data available. 

1 = Reads/Writes return immediately if no data available. 

Reads normally block until at least partial data can be returned. Writes, by default, block 
until all bytes requested have been written. Non-blocking mode (value is 1) changes this 
behavior as follows: 

• DosRead returns immediately with BytesRead = 0 (as defined in DosRead) if no 
data is available. 

• DosWrite returns immediately with BytesWritten = 0 (as defined in DosWrite) if 
insufficient buffer space is available in the pipe, or the entire data area is trans- 
ferred. 

14 Server or requester end; end-point of named pipe shown as follows: 

0 = Handle is the client end of a named pipe. 

1 = Handle is the server (requester) end of a named pipe. 

13-12 Reserved. 

11-10 Type of named pipe: 

00 = Pipe is a byte stream pipe. 

01 = Pipe is a message stream pipe. 

9-8 Read mode: 

00 = Read pipe as a byte stream. 

01 = Read pipe as a message stream. 

7 — 0 Instance count; 8-bit count to control pipe instances. When making the first instance of a 

named pipe, this field specifies how many instances can be created. Instances are as 
follows: 

Value Definition 

1 This can be the only instance (pipe is unique). 

-1 The number of instances is unlimited. 

0 Reserved value. 

re (USHORT) - return 

Return code descriptions are: 

0 NOERROR 

230 ERROR_BAD_PIPE 

233 ERROR_PIPE_NOT_CONNECTED 
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Query Named Pipe State 


Remarks 

At the serving end, the values returned by DosQNmPHandState are those originally established by 
DosMakeNmPipe or a subsequent DosSetNmPHandState. The values returned by the client end are those 
originally established by DosOpen or a subsequent DosSetNmPHandState. 

C Language 

Idefine INCL_DOSNMPIPES 

USHORT rc = DosQNmPHandState (Handle, Pi peHandl estate) ; 

HP I PE Handle; /* Pipe handle */ 

PUSHORT Pi peHandl estate; /* Pipe handle state */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQNmPHandState : FAR 
INCLJJOSNMPIPES EQU 1 

PUSH WORD Handle ;Pipe handle 

PUSHO WORD Pi peHandl estate ; Pi pe handle state (returned) 

CALL DosQNmPHandState 

Returns WORD 
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DosQNmPipelnfo - 
Query Named Pipe Info 


This call returns information for a named pipe. 


DosQNmPipelnfo (Handle, InfoLevel, InfoBuf, InfoBufSIze) 


Parameters 

Handle ( HPIPE ) - input 

Handle of the named pipe that is returned by DosMakeNmPipe or DosOpen. 

InfoLevel ( USHORT) - input 

Level of the required pipe information. Only level 1 file information is supported. 

InfoBuf (PBYTE) - output 

Address of the storage area that returns the requested level of named pipe information. For 
InfoLevel = 1 t file information is returned in the following format: 

outbufsize ( USHORT) 

Actual size of buffer for outgoing I/O. 

inbufsize (USHORT) 

Actual size of buffer for ingoing I/O. 

maxnumlnstances (UCHAR) 

Maximum allowed number of pipe instances. 

numlnstances (UCHAR) 

Current number of pipe instances. 

namelength (UCHAR) 

Length of pipe name. 

pipename (CHAR) 

Name of pipe (including WComputerName, if remote). 

InfoBufSIze ( USHORT) - input 
Length of InfoBuf. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

111 ERROR_BUFFER_OVERFLOW 

124 ERROR_INVALID_LEVEL 

230 ERROR_BAD_PIPE 

Remarks 

DosQNmPipelnfo returns all the information that fits in InfoBuf. 

For level 1 information, if the length of the name of the pipe is greater than 255 bytes, then a length of 
zero is returned in the length field. The full ASCIIZ name will still be returned in this case. 
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DosQNmPipelnfo - 
Query Named Pipe Info 

C Language 

typedef struct npi_datal { 

USHORT npi_obuflen; 

USHORT npijbuflen; 

UCHAR npijnaxicnt; 

UCHAR npi_curicnt; 

UCHAR npijiamlen; 

CHAR npi_name[l]; 

}; /* npijlatal */ 

#define INCL_DOSNMPIPES 

USHORT rc = DosQNmPipeInfo(Handle, InfoLevel, InfoBuf, InfoBufSize) ; 

HPIPE Handle; /* Pipe handle */ 

USHORT InfoLevel; /* Pipe data required ief 

PBYTE InfoBuf; fie Pipe data buffer ief 

USHORT InfoBufSize; fie Pipe data buffer size */ 

USHORT rc; fie return code ief 

Assembler Language 

EXTRN DosQNmPi pelnf o : FAR 
INCL_DOSNMPIPES EQU 1 

PUSH WORD Handle ;Pipe handle 

PUSH WORD InfoLevel ;Pipe data required 

PUSH@ OTHER InfoBuf ;Pipe data buffer 

PUSH WORD InfoBufSize ;Pipe data buffer size 

CALL DosQNmPipelnfo 

Returns WORD 


fie Pipelnfo data block (returned, level 1) ief 

fie length of outgoing I/O buffer ief 

fie length of incoming I/O buffer ief 

fie maximum number of instances ief 

fie current number of instances ief 

fie length of pipe name */ 

fie start of name ief 
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DosQNmPipeSemState - 
Query Named Pipe Operations 


This call returns information about local named pipes attached to a specific system semaphore. 


DosQNmPipeSemState (SemHandle, InfoBuf, InfoBufLen) 


Parameters 

SemHandle (i HSEM ) - input 

System semaphore handle that was previously attached to a named pipe by DosSetNmPipeSem. 
InfoBuf (PBYTE) - output 

Address of the buffer that contains records, or multiple records, for each named pipe: 
pipestatus (UCHAR) 

Coded value indicating the state of the named pipe: 

Value Definition 

0 End of information buffer (EOF). No more information records follow and subse- 
quent fields in this information record have no defined value. 

1 Read data available. 

2 Write space available. 

3 Pipe is closed. 

pipestate (UCHAR) 

Bit mask indicating additional information about the state of the named pipe: 

Bit Description 

7-1 Reserved 

0 A thread is waiting on the other end of the pipe, 

keyhandle (USHORT) 

Key value associated with SemHandle at the time of the call to DosSetNmPipeSem. 

plpedata (USHORT) 

Pipe “data or space” availability state: 

Value Definition 

1 Amount of read space available in the pipe. 

2 Amount of write data available in the pipe. 

InfoBufLen (USHORT) - input 
Size in bytes of InfoBuf. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

87 ERROR_INVALID_PARAMETER 

111 ERROR_BUFFER_OVERFLOW 

Remarks 

A record is placed in InfoBuf for each local named pipe that has a semaphore attached whose handle 
matches the handle specified and whose state is closed or allows blocking mode I/O to be done. 

There is no guarantee that records in the buffer refer to named pipes opened by the process making this 
call. If the same system semaphore is attached to different named pipes by multiple processes, informa- 
tion about named pipes that are not accessible to the caller can be returned. Thus, cooperating proc- 
esses should agree on a convention for key values to help identify the named pipes of interest. A key 
value is associated with the pipe at the time the semaphore is set with DosSetNmPipeSem. 

If a process wants data in the buffer to refer only to its own named pipes, it must use an exclusive system 
semaphore. 
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DosQNmPipeSemState - 
Query Named Pipe Operations 


A process associates a single semaphore with multiple pipes by way of DosSetNmPipeSem. After waking 
up from a wait on the semaphore, a thread issues DosQNmPipeSemState, which returns the I/O state 
information for all pipes associated with the semaphore. The thread can scan this information to deter- 
mine which pipes can be read or written. This is more efficient than polling the pipes with a non-blocking 
I/O on each pipe. 

C Language 

typedef struct npss { 

UCHAR npss_status; 

UCHAR npss_flag; 

USHORT npss_key; 

USHORT npss_avai 1 ; 

}; /* npss */ 

#define INCLJ50SNMPIPES 

USHORT rc s DosQNmPipeSemState (SemHandle, InfoBuf, InfoBufLen); 

HSEM SemHandle; /* Semaphore handle */ 

PBYTE InfoBuf; /* Address of returned info */ 

USHORT InfoBufLen; /* Length of InfoBuf */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQNmPi peSemState : FAR 
INCL_D0SNMP1PE$ EQU 1 

PUSH DWORD SemHandle Semaphore handle 

PUSH§ OTHER InfoBuf information (returned) 

PUSH WORD InfoBufLen ; Length of InfoBuf 

CALL DosQNmPipeSemState 

Returns WORD 


/* QNmPi peSemState information record */ 
/* type of record, Q=E0I, l=read ok, */ 
/* 2 = write ok, 3 = pipe closed */ 

/* additional info, 01 a waiting thread */ 
/* user's key value */ 

/* available data/space if status-1/2 */ 


2-270 Control Program Programming Reference 



FAPI DosQPathlnfo - 

Query File or Subdirectory for Information 


DosQPathlnfo returns attribute and extended attribute information for a file or subdirectory. 


DosQPathlnfo (PathName, PathlnfoLevel, PathlnfoBuf, PathtnfoBufSize, Reserved) 


Parameters 

PathName (PSZ) - input 

Address of the ASCIIZ full path name of the file or subdirectory. Global file name characters can be 
used in the name only for PathlnfoLevels five and six. 

DosQSysinfo is called by an application during initialization to determine the maximum path length 
allowed by OS/2. 

PathlnfoLevel (USHORT) - input 

Level of path information required. A value of 1, 2, 3, 5, or 6 can be specified. Level 4 is reserved. 
The structures described in PathlnfoBuf indicate the information returned for each of these levels. 

PathlnfoBuf (PBYTE) - output 

Address of the storage area containing the requested level of path information. Path information, 
where applicable, is based on the most recent DosClose, DosBufReset, DosSetFiielnfo, or 
DosSetPathlnfo. 

Level 1 Information 

PathlnfoBuf contains the following structure, to which path information is returned: 
filedate (FDATE) 

Structure containing the date of creation. 

Bit Description 

15-9 Year, in binary, of creation 

8-5 Month, in binary, of creation 

4-0 Day, in binary, of creation. 

filetfme (FUME) 

Structure containing the time of creation. 

Bit Description 

15-11 Hours, in binary, of creation 

10-5 Minutes, in binary, of creation 

4 — 0 Seconds, in binary number of two-second increments, of creation, 

fileaccessdate (FDATE) 

Structure containing the date of last access. See FDATE in filedate. 
fileaccesstime (FTtME) 

Structure containing the time of last access. See FTIME in filetime, 
writeaccessdate (FDATE) 

Structure containing the date of last write. See FDATE in filedate. 
writeaccesstime (FTIME) 

Structure containing the time of last write. See FTIME in filetime. 

filesize (ULONG) 

File size. 

filealloc (ULONG) 

Allocated file size. 

fileattrib (USHORT) 

Attributes of the file, defined in DosSetFileMode. 
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DosQPathlnfo - 

Query File or Subdirectory for Information 


FAPI 


Level 2 Information 

PathlnfoBuf contains a structure similar to the Level 1 structure, with the addition of the cbList 
field after the fileattrib field. 

cbList (ULONG) 

On output, this field contains the length of the entire EA set for the file object. This value 
can be used to calculate the size of the buffer required to hold EA information returned 
when PathlnfoLevel = 3 is specified. 

Level 3 Information 

PathlnfoBuf contains an EAOP structure, which has the following format: 
fpGEALIst (PGEALIST) 

Address of GEAList. GEAList is a packed array of variable length "get EA M structures, each 
containing an EA name and the length of the name. 

fpFEALIst (PFEALIST) 

Address of FEALIst. FEAList is a packed array of variable length "full EA” structures, each 
containing an EA name and its corresponding value, as well as the lengths of the name and 
the value. 

oError (ULONG) 

Offset into structure where error has occurred. 

On input, PathlnfoBuf is an EAOP structure. fpGEAList points to a GEA list defining the attribute 
names whose values are returned. fpFEAList points to a data area where the relevant FEA list is 
returned. The length field of this FEA list is valid, giving the size of the FEA list buffer. oError 
points to the offending GEA entry in case of error. Following is the format of the GEAList 
structure: 

cbList (ULONG) 

Length of the GEA list, including the length itself, 
list (GEA) 

List of GEA structures. A GEA structure has the following format: 
cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character. 

szName (CHAR) 

ASCIIZ name of EA. 

On output, PathlnfoBuf is unchanged. The buffer pointed to by fpFEAList is filled in with the 
returned information. If the buffer fpFEAList points to isn't large enough to hold the returned 
information (ERROR_BUFFER_OVERFLOW) cbList is still valid, assuming there's at least enough 
space for it. Its value is the size of the entire EA set for the file, even though only a subset of 
attributes was requested. Following is the format of the FEAList structure: 

cbList (ULONG) 

Length of the FEA list, including the length itself, 
list (FEA) 

List of FEA structures. An FEA structure has the following format: 

Flags (BYTE) 

Bit indicator describing the characteristics of the EA being defined. 

Bit Description 

15 Critical EA. 

14-0 Reserved and must be set to zero. 

If bit 15 is set to 1, this indicates a critical EA. If bit 15 is 0, this means the EA is noncrit- 
ical; that is, the EA is not essential to the intended use by an application of the file with 
which it is associated. 

cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character. 
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fapi DosQPathlnfo - 

Query File or Subdirectory for Information 

cbValue ( USHORT) 

Length of EA value, which cannot exceed 64KB. 
szName (PSZ) 

Address of the ASCIIZ name of EA. 
aValue (PSZ) 

Address of the free-format value of EA. 

Note: The szName and aValue fields are not included as part of header or include files. 
Because of their variable lengths, these entries must be built manually. 

Level 5 Information 

Level 5 returns the fully qualified ASCIIZ name of PathName In PathlnfoBuf. The PathName may 
contain global file name characters. 

Level 6 Information 

Level 6 requests a file system to verify the correctness of PathName per its rules of syntax. An 
erroneous name is indicated by an error return code. The PathName may contain global file 
name characters. 

PathlnfoBufSize ( USHORT) - output 
Length of PathlnfoBuf. 

Reserved ( ULONG ) - input 

Reserved, must be set to zero. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

3 E R R O R_P ATH_N OT_FOU N D 

32 ERROR_SHARING_VIOLATION 

111 ERROR_BUFFER_OVERFLOW 

124 ERRORJNVALIDJ.EVEL 

206 ERROR_FILENAMEJEXCED_RANGE 

254 ERRORJNVALID_EA_NAME 

255 E R ROR_E A_LIST J NCONS I STE NT 

Remarks 

For DosQPathlnfo to return information contained in any of the file information levels, the file object must 
be opened for read access, with a deny-write sharing mode specified for access by other processes. 
Thus, if the file object is already accessed by another process that holds conflicting sharing and access 
rights, a call to DosQPathlnfo fails. 

C Language 

typedef struct _FDATE { /* fdate */ 

unsigned day : 5; /* binary day for directory entry */ 

unsigned month : 4; /* binary month for directory entry */ 

unsigned year : 7; /* binary year for directory entry */ 

} FDATE; 

typedef struct _FTIME { /* ftime */ 

unsigned twosecs : 5; /* binary number of two-second increments */ 

unsigned minutes : 6; /* binary number of minutes */ 

unsigned hours : 5; /* binary number of hours */ 

} FTIME; 
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DosQPathlnfo - 

Query File or Subdirectory for Information 


FAPI 


typedef struct _FILESTATUS { /* fsts */ 

FDATE fdateCreation; /* date of file creation */ 

FUME ftimeCreation; /* time of file creation */ 

FDATE fdateLastAccess; /* date of last access */ 

FT I ME ftimeLast Access; /* time of last access */ 

FDATE fdateLastWrite; /* date of last write */ 

FT I ME ftimeLastWrite; /* time of last write */ 

ULONG cbFile; /* file size (end of data) */ 

ULONG cbFileAlloc; /* file allocated size */ 

USHORT attrFile; /* attributes of the file */ 

} FILESTATUS; 

typedef struct _GEA { /* gea */ 

BYTE cbName; /* name length not including NULL */ 

CHAR szNamefl]; /* attribute name */ 

} GEA; 

typedef struct J5EALIST { /* geal */ 

ULONG cbList; /* total bytes of structure including full list */ 

GEA list [1] ; /* variable length GEA structures */ 

} GEALIST; 

typedef struct _FEA { /* fea */ 

BYTE fEA; /* flags */ 

BYTE cbName; /* name length not including NULL */ 

USHORT cbValue; /* value length */ 

} FEA; 

typedef struct _FEALIST { /* feal */ 

ULONG cbList; /it total bytes of structure including full list */ 

FEA list [1] ; /it variable length FEA structures it/ 

} FEAL I ST; 

typedef struct _EA0P { /it eaop */ 

PGEALIST fpGEAList; /it general EA list it/ 

PFEALIST fpFEAList; /it full EA list it/ 

ULONG oError; 

} EAOP; 

Idefine INCL_DOSFILEMGR 

USHORT rc = DosQPathInfo(PathName, PathlnfoLevel , PathlnfoBuf, PathlnfoBufSize, 0); 

PSZ PathName; /it File or directory path name string it/ 

USHORT PathlnfoLevel; /it Data required */ 

PBYTE PathlnfoBuf; /it Data buffer (returned) it/ 

USHORT PathlnfoBufSize; /★ Data buffer size it/ 

ULONG 0; /* Reserved (must be zero) it/ 

USHORT rc; /it return code it/ 
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Query File or Subdirectory for Information 

Assembler Language 

FDATE st rue 
fdate_fs dw ? 

FDATE ends 

FT I ME struc 
ftime_fs dw ? 

FUME ends 

FILESTATUS struc 

fsts_fdateCreation dw (size FDATE) /2 dup (?) ;date of file creation 

fsts_ftimeCreation dw (size FTIME)/2 dup (?) ; time of file creation 

fstsjfdateLastAccess dw (size FDATE) /2 dup (?) ;date of last access 

f sts~fti meLast Access dw (size FTIME)/2 dup (?) ;time of last access 

fsts_fdateLastWrite dw (size FDATE) fZ dup (?) ;date of last write 

fsts_ftimeLastWrite dw (size FTIME)/2 dup (?) ;time of last write 

f$ts~cbFile dd ? ; f i 1 e size (end of data) 

f sts_cbFi 1 eAl 1 oc dd ? ;file allocated size 

fsts_attrFile dw ? ; attributes of the file 

FILESTATUS ends 
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DosQPathlnfo - 

Query File or Subdirectory for Information 


FAPI 


GEA struc 

gea_cbName db ? ;natne length not including NULL 

gea_szName db 1 dup (?) ; attribute name 

GEA ends 

GEALIST struc 

geal_cbList dd ? ; total bytes of structure including full list 

gealjist db size GEA * 1 dup (?) ; variable length GEA structures 

GEALIST ends 

FEA struc 

fea_fEA db ? ; flags 

fea_cbName db ? ;name length not including NULL 
fea_cbValue dw ? ; value length 

FEA ends 

FEALIST struc 

feal_cbList dd ? ;total bytes of structure including full list 

fealjist db size FEA * 1 dup (?) ; variable length FEA structures 

FEALIST ends 

EAOP struc 

eaop_fpGEALi st dd ? jgeneral EA list 
eaop_f pFEALi st dd ? ; ful 1 EA list 

eaop_oError dd ? ; 

EAOP ends 

EXTRN DosQPathlnfo: FAR 
INCL_DO$FILEMGR EQU 1 

PUSH@ ASCII? PathName ; Fi 1 e or directory path name string 

PUSH WORD PathlnfoLevel ;Data required 

PUSH® OTHER PathlnfoBuf ;Data buffer (returned) 

PUSH WORD PathlnfoBuf Size ;Data buffer size 

PUSH DWORD 0 Reserved (must be zero) 

CALL DosQPathlnfo 

Returns WORD 
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DosQSysInfo - 

Query System Variable Information 


This call returns values of static system variables. 


DosQSysInfo (Index, DataBuf, DataBufLen) 

Parameters 

Index ( USHORT) - input 

Ordinal of the system variable to return. 

Index = 0 indicates maximum path length. The maximum path length is returned in the first 
word of the DataBuf. 

DataBuf (PBYTE) - output 

Address where the system returns the variable value. 

DataBufLen ( USHORT) - input 
Length of the data buffer. 

rc ( USHORT) - return 

Return code descriptions include: 

0 NO.ERROR 

87 ERROR JNVALID_PAR AM ETER 

111 ERROR_BUFFER_OVERFLOW 

Remarks 

An OS/2 application may want to reference file objects managed by an installable file system that sup- 
ports long file names. Because some installable file systems may support longer names than others, an 
application should issue DosQSysInfo upon initialization. 

DosQSysInfo returns the maximum path length supported by the file system currently installed. The path 
length includes the drive specifier (d:), the leading "\” and the trailing null character. 

The value returned by DosQSysInfo can be used to allocate buffers for storing path names returned by 
requests, for example, to DosFindFIrst and DosFindNext. 

C Language 

#define INCLJ30SFILEMGR 

USHORT rc = DosQSysInfo( Index, DataBuf, DataBufLen); 

USHORT Index; /* Which variable */ 

PBYTE DataBuf; /* System information (returned) */ 

USHORT DataBufLen; /* Data buffer size */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQSysInfo: FAR 
INCL_DOSFILEMGR EQU 1 

PUSH WORD Index ; Which variable 

PUSH® OTHER DataBuf ; System Information (returned) 

PUSH WORD DataBufLen ;Data buffer size 

CALL DosQSysInfo 

Returns WORD 
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DosQueryQueue - 
Query Size off Queue 


This call determines the number of elements in a queue. 


DosQueryQueue (QueueHandle, NumberElements) 


Parameters 

QueueHandle ( HQUEUE ) - input 
Handle off the queue to find size. 

NumberElements ( PUSHORT) - output 

Address off the number off entries in the queue waiting to be processed. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

337 ERROR_QUEJNVALIDJHANDLE 

Remarks 

Any thread off a process that has access to the queue (because of a DosCreateQueue or a DosOpenQueue 
request) may issue DosQueryQueue to determine the number of elements currently in the queue. 

If the process that created the queue closes it before this request is issued, 
ERROR_QUE_INVALID_HANDLE is returned. 

C Language 

#define INCLJ50SQUEUES 

USHORT rc = DosQueryQueue (QueueHandle, NumberElements); 

HQUEUE QueueHandle; /* Queue handle */ 

PUSHORT NumberElements; /* Size of the queue (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQueryQueue : FAR 
INCLJ30SQUEUES EQU 1 

PUSH WORD QueueHandle ; Queue handle 

PUSH® WORD NumberElements ;Size of the queue (returned) 

CALL DosQueryQueue 

Returns WORD 
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FAPI 


DosQVerify - 
Query Verify Setting 


This call returns the value of the verify flag. 


DosQVerify (VerifySetting) 


Parameters 

VerifySetting ( PUSHORT) - output 

Address of the verify mode for the process. 

Value Definition 

00H Verify mode is not active. 

01 H Verify mode is active. 

rc ( USHORT) - return 

Return code description is: 

0 NO.ERROR 

Remarks 

When verify is active, OS/2 performs a verify operation each time it does a file write to assure proper 
data recording on the disk. Although disk recording errors are rare, this function has been provided for 
applications to verify the proper recording of critical data. 

C Language 

Idefine INCL_DOSFILEHGR 

USHORT rc = DosQVerify (VerifySetting) ; 

PUSHORT VerifySetting; /* Verify setting (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosQVerify: FAR 
INCL.DOSFILEMGR EQU 1 

PUSH? WORD VerifySetting ‘.Verify setting (returned) 

CALL DosQVerify 

Returns WORD 
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DosR2StackRealloc - 
Reallocate Privilege Level 2 Stack 


This caii changes the size of a thread’s privilege level 2 stack. 


DosR2StackRealloc (NewSIze) 


Parameters 

NewSize ( USHORT) - input 

New size, in bytes, for the privilege level 2 stack. The stack is reallocated as required and the TSS 
SP pointer is adjusted accordingly. The new stack size can not be less than the current stack size. 

rc (USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOT_ENOUGH_MEMORY 

196 ERROR_DYNLINKFROMJNVALID_RING 

197 ERRORJOPL_NOT_ENABLED 

207 ERROR_RING2_STACK INJJSE 

216 ERROR_CANNOT_SHRINK 

Remarks 

This call is provided to allow the privilege level 2 stack to be resized and to have the TSS adjusted to 
reflect the new size. The size can not be less than the current size. 

This call can not be made from privilege level 2. 

C Language 

#def i ne INCL_00SDEVICES 

USHORT rc = DosR2StackRealloc(NewSize) ; 

USHORT NewSize; /* The new size in bytes for the stack */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosR2StackReal 1 oc : FAR 
INCL_DOSDEVICES EQU 1 

PUSH WORD NewSize ;The new size in bytes for the stack 

CALL DosR2StackRea11oc 

Returns WORD 
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FA PI 


DosRead - 
Read from File 


This call reads the specified number of bytes from a file, pipe, or device to a buffer location. 


DosRead (FileHandle, BufferArea, BufferLength, BytesRead) 


Parameters 

FileHandle ( HFILE ) - input 

File handle obtained from DosOpen. 

BufferArea (PVOID) - output 
Address of the input buffer. 

BufferLength ( USHORT) - input 
Length, in bytes, to be read. 

BytesRead ( PUSHORT) - output 

Address of the number of bytes read. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

6 ERROR JNVALIDJHANDLE 

26 ERROR_NOT_DOS_DISK 

33 ERRORLOCKVIOLATION 

109 ERROR_BROKEN_PIPE 

234 ERROR_MORE_DATA 

Remarks 

The requested number of bytes may not be read. If the value returned in BytesRead is zero, the process 
has tried to read from the end of the file. 

A BufferLength value of zero is not considered an error. In the case where BufferLength is zero, the 
system treats the request as a null operation. 

The file pointer is moved to the desired position by reading, writing, or issuing DosChgFilePtr. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to DosRead when coding for the DOS mode: 

• Only single-byte DosRead calls may be made to the COM device, because the COM device driver for 
the DOS environment does not support multiple-byte I/O. 

• When DosRead is called with a handle that is open to CON, the read goes directly through 
KbdStringln using the buffer and length that are provided to DosRead. This causes a DOS mode 
DosRead to behave differently than an OS/2 mode DosRead. Because an OS/2 mode DosRead 
buffers the call to KbdStringln, this allows the user to enter many more characters. 

For example, suppose DosRead is called with a buffer of length 10 from a handle opened to CON: 

- In OS/2 mode, the user is allowed to enter a large number of characters before KbdStringln 
begins beeping (indicating the buffer is full). After carriage return is pressed, KbdStringln 
returns to DosRead. DosRead returns the first 10 characters to the caller and the remaining 
characters on subsequent calls to DosRead from CON. 

— In DOS mode, the user is allowed to enter only eight characters (DOS mode DosRead reserves 
two characters for CR and LF) before KbdStringln begins beeping. DosRead returns the eight 
characters entered, followed by CR and LF to the calling program. 
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DosRead - fapi 

Read from File 


Named Pipe Considerations 

A named pipe is read as one of the following: 

• A byte pipe in byte read mode 

• A message pipe in message read mode 

• A message pipe in byte read mode. 

A byte pipe must be in byte read mode to be read; an error is returned if it is in message read mode. All 
currently available data, up to the size requested, is returned. 

A message pipe can be read in either message read mode or byte read mode. When the message pipe is 
in message read mode, a read that is larger than the next available message returns only that message. 
BytesRead is set to indicate the size of the message returned. 

A read that is smaller than the next available message returns with the number of bytes requested and 
an ERROR_MORE_DATA return code. When resuming the reading of a message after 
ERROR_MORE_DATA is returned, a read always blocks until the next piece (or the rest) of the message 
can be transferred. DosPeekNmPipe may be used to determine how many bytes are left in the message. 

A message pipe in byte read mode is read as if it were a byte stream, skipping over message headers. 
This is like reading a byte pipe in byte read mode. 

When blocking mode is set for a named pipe, a read blocks until data is available. In this case, the read 
never returns with BytesRead = 0 except at EOF. In message read mode, messages are always read in 
their entirety, except in the case where the message is bigger than the size of the read. 

Non-blocking mode allows a return with BytesRead = 0 only when no data is available at the time of the 
read. 

C Language 

^define INCL_DO$FILEMGR 

USHORT rc s DosRead (FileHandle, BufferArea, Buffer Length, BytesRead); 


HFILE 

FileHandle; 

/* File Handle */ 

PVOID 

BufferArea ; 

/* User buffer (returned) */ 

USHORT 

BufferLength; 

/* Buffer length */ 

PUSHORT 

BytesRead; 

/* Bytes read (returned) */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosRead: FAR 


INCLJJOSFILEMGR EQU 1 


PUSH 

WORD 

FileHandle 

;File Handle 

PUSH# 

OTHER 

BufferArea 

;User buffer (returned) 

PUSH 

WORD 

BufferLength 

; Buffer length 

PUSH# 

CALL 

WORD 

DosRead 

BytesRead 

; Bytes read (returned) 


Returns WORD 
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DosReadAsync - 
Asynchronous Read from File 


This call asynchronously transfers the specified number of bytes from a file, pipe, or device to a buffer. 


DosReadAsync (FileHandle, RamSemaphore, ReturnCode, BufferArea, 
BufferLength, BytesRead) 


Parameters 

FileHandle (HFILE) - input 

File handle obtained from DosOpen. 

RamSemaphore ( PULONG ) - input 

Address used by the system to signal the caller that the read operation is complete. 

ReturnCode (PUSHORT) - output 

Address of the I/O error return code. 

BufferArea ( PVOID ) - output 
Address of the input buffer. 

BufferLength ( USHORT) - input 
Length, In bytes, to be read. 

BytesRead (PUSHORT) - output 

Address of the number of bytes read. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

6 ER ROR JN VALI D _H AN DLE 

26 ERROR_NOT_DOS_DISK 

33 ERROR_LOCK_VIOLATION 

89 ERROR_NO_PROC_SLOTS 

109 ERROR_BROKEN_PIPE 

Remarks 

The requested number of bytes may not be read. If the value in BytesRead is zero, the process tried to 
read from the end of the file. 

A BufferLength value of zero is not considered an error. In the case where BufferLength is zero, the 
system treats the request as a null operation. 

The file pointer is moved to the desired position by reading, writing, or issuing DosChgFilePtr. 

A call to DosReadAsync may return before the read is complete. To wait for an asynchronous read to 
complete, RamSemaphore must be set by the application before the DosReadAsync call is made. The 
application issues DosSemSet to set the semaphore, calls DosReadAsync, and then issues DosSemWait, 
to wait to be signaled by the system that the asynchronous read is complete. When RamSemaphore is 
cleared and the read operation is complete, ReturnCode can be checked. 

Note: If it is necessary to make a DosReadAsync request from within a segment that has I/O privilege, 
DosCallback may be used to invoke a privilege level 3 segment that actually issues the 
DosReadAsync request. 
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Asynchronous Read from File 


Named Pipe Considerations 

A named pipe is read as one of the following: 

• A byte pipe in byte read mode 

• A message pipe in message read mode 

• A message pipe in byte read mode. 

A byte pipe must be in byte read mode to be read; an error is returned if it is in message read mode. All 
currently available data, up to the size requested, is returned. 

When a message pipe is read in message read mode, a read that is larger than the next available 
message returns only that message and BytesRead is set to indicate the size of the message returned. 

A read that is smaller than the next available message returns with the number of bytes requested and 
an ERROR_MOREJDATA return code. When resuming the reading of a message after 
ERROR_MORE_DATA is returned, a read always blocks until the next piece (or rest) of the message can 
be transferred. DosPeekNmPipe may be used to determine how many bytes are left in the message. 

A message pipe in byte read mode is read as if it were a byte stream, skipping over message headers. 
This is like reading a byte pipe in byte read mode. 

When blocking mode is set for a named pipe, a read blocks until data is available. In this case, the read 
never returns with BytesRead = 0 except at EOF. In message read mode, messages are always read in 
their entirety, except in the case where the message is bigger than the size of the read. 

Non-blocking mode allows a return with BytesRead = 0 only when trying to read at the start of a message 
and no message is available. 

C Language 

#define INCLJ50SFILEMGR 

USHORT rc = DosReadAsync (FileHandle, RamSemaphore, ReturnCode, BufferArea, 

BufferLength, BytesRead); 


HFILE 

FileHandle; 

/* File handle */ 

PULONG 

RamSemaphore 

; /*■ Ram semaphore */ 

PUSHORT 

ReturnCode; 

/* I/O operation return code (returned) */ 

PV0I0 

BufferArea; 

/* User buffer (returned) */ 

USHORT 

BufferLength 

; /* Buffer length */ 

PUSHORT 

BytesRead; 

/* Bytes read (returned) */ 

USHORT 

rc; 

/* return code */ 

Assembler Language 

EXTRN DosReadAsync ; FAR 

INCL_DQSFILEMGR EQU 1 

PUSH WORD 

Fi 1 eHandl e 

;File handle 

PUSH® DWORD 

RamSemaphore 

;Ram semaphore 

PUSH® WORD 

ReturnCode 

; I/O operation return code (returned) 

PUSH® OTHER 

BufferArea 

;User buffer (returned) 

PUSH WORD 

BufferLength 

; Buffer length 

PUSH® WORD 

BytesRead 

; Bytes read (returned) 


CALL DosReadAsync 
Returns WORD 
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DosReadQueue - 
Read from Queue 


This call reads an element from a queue and removes it. 


DosReadQueue (QueueHandle, Request, DataLength, DataAddress, ElementCode, NoWalt, 
ElemPriorlty, SemaphoreHandle) 


Parameters 

QueueHandle ( HQUEUE ) - input 
Handle of the queue to read from. 

Request ( PULONG ) — output 

Address of a data field that returns the following information. 

The first word is the PID of the process that added the element to the queue. 

The second word is used for event encoding by the application. The data in this word is the same as 
that furnished by the Request parameter on the DosWriteQueue request for the corresponding queue 
element. 

DataLength {PUSHORT) - output 

Address of the length of the data being received. 

DataAddress ( PULONG ) - output 

Address of the element being received from the queue. 

ElementCode (USHORT) - input 

Overrides the normal priority, FIFO-, or LIFO-read ordering. This operand is used to identify a spe- 
cific element that is to be read. This field can be set to zero to read the first element in the queue, or 
it can contain an identifier for a particular element, which was returned to ElementCode by a 
DosPeekQueue request. 

NoWalt (UCHAR) - input 

Action to be performed when no entries are found in the queue. 

Value Definition 

0 The requesting thread waits. 

1 The requesting thread does not wait. 

ElemPriorlty {PBYTE) - output 

Address of the element's priority. This is the value that was specified for ElemPriority by the 
DosWriteQueue call that added the element to the queue. ElemPriority is a numeric value in the 
range of 0 to 15, with 15 being the highest priority. 

SemaphoreHandle ( HSEM ) - input 

Handle of the semaphore cleared when an element is written to the queue and NoWait=0 is speci- 
fied. If NoWait=1 is specified, this parameter should be set to null. 

The semaphore can be either a RAM or system semaphore. If the semaphore is a RAM semaphore, 
it must be in a segment that is shared between the process that owns the queue and any process that 
issues a DosWriteQueue request to the queue. 

If multiple threads are processing elements from the queue using NoWait=0, the same semaphore 
must be provided on ail DosPeekQueue or DosReadQueue requests. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

330 ERROR_QUE_PROC_NOT_OWNED 

333 ERROR_QUE_ELEMENT_NOT_EXIST 

337 ERROR_QUEJNVALIDJHANDLE 

342 ERROR_QUE_EMPTY 

433 E R R O R_Q U E J N V ALI D_W A IT 
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DosReadQueue - 
Read from Queue 


Remarks 

A process that creates a queue with DosCreateQueue owns it. Only the owning process and any threads 
it creates can issue DosReadQueue to remove an element from the queue. If the queue is empty and 
NoWait = 0 is specified, the thread waits for an element to be written to the queue. If the queue is empty 
and NoWait = 1 is specified, the thread returns with ERROR_QUE_EMPTY. 

If ElementCode is set to zero, the elements in the queue are removed in the order specified at the time of 
the queue’s creation (FIFO, LIFO, or priority). 

ElementCode can also be set to a value returned by DosPeekQueue, which uses ElementCode to return 
identifiers for successive queue elements. The assigning of identifiers by DosPeekQueue to individual 
queue elements allows the queue owner to examine a queue element with DosPeekQueue and compare 
it with a queue element it has read. 

The semaphore provided by SemaphoreHandle is typically used by a DosMuxSemWait request to wait for 
an element to be written to a queue or other events. If DosReadQueue is issued with NoWait=0, it clears 
the semaphore indicated by SemaphoreHandle as soon as the element is read. 

The Request, DataLength and DataAddress parameters contain data understood by the thread adding the 
element to the queue and by the thread that receives the queue element. There is no special meaning to 
this data; applications may use these parameters for any purpose they wish. OS/2 does not alter this 
data; it simply copies this data intact. OS/2 does not validate the address of DataBuffer or the 
DataLength. 


C Language 

fdefine INCL_DOSQUEUES 


USHORT rc = DosReadQueue (QueueHandle, Request, DataLength, DataAddress, 

ElementCode, NoWait, ElemPriority, SemaphoreHandle); 


HQUEUE 

QueueHandle; 

/* Queue handle */ 

PULONG 

Request ; 

fie Request identification data (returned) ie/ 

PUSHORT 

DataLength; 

/ie Length of element received (returned) */ 

PULONG 

DataAddress; 

/* Address of element received (returned ie/ 

USHORT 

ElementCode; 

/ie Indicate want a particular element */ 

UCHAR 

NoWait; 

/ie Indicate to not wait if queue is empty ie/ 

PBYTE 

ElemPriority; 

/ie Priority of element (returned) ie/ 

HSEM 

SemaphoreHandle; 

/ie Semaphore handle ie/ 

USHORT 

rc; 

/ie return code ie/ 


Assembler Language 

EXTRN DosReadQueue : FAR 
INCL_DOSQUEUES EQU 1 


PUSH 

PUSH® 

PUSH® 

PUSH® 

PUSH 

PUSH 

PUSH® 

PUSH 

CALL 


WORD QueueHandle 

DWORD Request 

WORD DataLength 

DWORD DataAddress 

WORD ElementCode 

OTHER NoWait 

BYTE ElemPriority 

DWORD SemaphoreHandl e 

DosReadQueue 


; Queue handle 

; Request identification data (returned) 
; Length of element received (returned) 

; Address of element received (returned) 
indicate want a particular element 
; Indicate to not wait if queue is empty 
; Priority of element (returned) 

; Semaphore handle 


Returns WORD 
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FAPI 


DosReallocHuge - 
Change Huge Memory Size 


This call changes the size of memory originally allocated by DosAllocHuge. 


DosReallocHuge (NumSeg, Size, Selector) 


Parameters 

NumSeg ( USHORT) - input 

Number of 65536 byte segments requested. 

Size (USHORT) - input 

Number of bytes requested in the last non-65536 byte segment. A value of 0 indicates none. 
Selector (SEL) - input 

Selector returned on a previous DosAllocHuge. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOTJENOUGH_MEMORY 

87 ERRORJNVALIDPARAMETER 

Remarks 

DosReallocHuge is called to change the size of unshared or shared huge memory allocated by 
DosAllocHuge. The selector used for this call must be the one returned by the DosAllocHuge request. 

Normally, segments allocated as shared (AllocFlags bits 0 and 1 were set) cannot be decreased in size. 
However, if AllocFlags bit 3 was also set, the shared segment’s size can be decreased. 

DosReallocHuge Is also called to reallocate a segment allocated as discardable (AllocFlags bit 2 set) 
after the segment is discarded by the system. The call to DosReallocHuge automatically locks the 
segment for access by the caller, the same as if a DosLockSeg had been issued. 

Note: This request may be issued from privilege level 2 or 3. However, only a privilege level 3 huge 
segment is valid. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restriction applies to DosReallocHuge when coding for the DOS mode: 

The requested Size value is rounded up to the next paragraph (16-byte). 


C Language 

Ideflne INCLJWSMEMMGR 

USHORT rc s DosReallocHuge (NumSeg, Size, Selector); 


USHORT 

USHORT 

SEL 

NumSeg; 

Size; 

Selector; 

/* Number of 65536-byte segments requested */ 
/* Number of bytes in last segment */ 

/* Selector */ 

USHORT 

rc; 

/* return code */ 
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DosReallocHuge - 
Change Huge Memory Size 


FAPI 


Assembler Language 

EXTRN DosReallocHuge: FAR 
INCL_DOSMEMMGR EQU 1 

PUSH WORD NumSeg ; Number of 65536-byte segments requested 

PUSH WORD Size ; Number of bytes in last segment 

PUSH WORD Selector ; Selector 

CALL DosReallocHuge 

Returns WORD 
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FAPI 


DosReallocSeg - 
Change Segment Size 


This call reallocates a segment after discard or changes the size of a segment already allocated. 


DosReallocSeg (Size, Selector) 


Parameters 

Size ( USHORT) - input 

New requested segment size (in bytes). A value of 0 indicates 65536 bytes. 

Selector (SEL) - input 
Segment to be resized. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

5 ERROR_ACCESS_DENIED 

8 ERROR_NOT_ENOUGH_MEMORY 

Remarks 

DosReallocSeg is called to change the size of an unshared or shared segment allocated with a 
DosAllocSeg request. 

Normally, segments allocated as shared (AllocFlags bits 0 and 1 were set) cannot be decreased in size. 
However, if AllocFlags bit 3 was also set, the shared segment’s size can be decreased. 

DosReallocSeg is also called to reallocate a segment allocated as discardable (AllocFlags bit 2 set) after 
the segment is discarded by the system. The call to DosReallocSeg automatically locks the segment for 
access by the caller, the same as if a DosLockSeg had been issued. 

Note: This request may be issued from privilege level 2 or 3, and the segment being resized can be 
either a privilege level 2 or privilege level 3 segment. 

To change the size of huge memory allocated by DosAllocHuge, see DosReallocHuge. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restriction applies to DosReallocSeg when coding for the DOS mode. The requested Size value is 
rounded up to the next paragraph (16-byte). 


C Language 

#def1ne INCLJJOSMEMMGR 

USHORT rc = DosReallocSeg (Size, Selector); 


USHORT 

Size; 

/* New size requested in bytes */ 

SEL 

Selector; 

/* Selector */ 

USHORT 

rc; 

/* return code */ 
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DosReallocSeg - 
Change Segment Size 


FAPI 


Assembler Language 

EXTRN DosReallocSeg: FAR 
INCL_DOSMEMMGR EQU 1 

PUSH WORD Size ;New size requested in bytes 

PUSH WORD Selector Selector 

CALL DosReallocSeg 

Returns WORD 
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DosResumeThread - 
Restart Thread 


This call restarts a thread previously stopped with a DosSuspendThread call. 


DosResumeThread (ThreadID) 


Parameters 

ThreadID (TID) - input 

Thread ID of the resumed thread. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

309 ERRORJNVALIDJTHREADID 

C Language 

fdefine INCL.DOSPROCESS 

USHORT rc = DosResumeThread (Threadl D) ; 

TID ThreadID; /* Thread ID of thread to resume */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosResumeThread : FAR 
I NCL_D0S PROCESS EQU 1 

PUSH WORD ThreadID ; Thread ID 

CALL DosResumeThread 

Returns WORD 

Example 

The following example shows how to suspend and resume execution of a thread within a process. The 
main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that prints 
a line and then sleeps, relinquishing its time slice to the main thread. After one iteration by Thread2, the 
main thread suspends Thread2 and then resumes it. Subsequently, Thread2 completes the remaining 
three iterations. 
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DosResumeThread 
Restart Thread 


#define INCL_DOSPROCESS 
#include <os2.h> 

#define SEGSI2E 4000 /* Number of bytes requested in segment */ 

Idefine ALLOCFLAGS 0 /* Segment allocation flags - no sharing */ 

Idefine SLEEPSHORT 5L /* Sleep interval - 5 milliseconds */ 

#define SLEEPLONG 75L /* Sleep interval - 75 milliseconds */ 

Idefine RETURN_CODE 0 /* Return code for OosExit() */ 

VOID API ENTRY Thread2() 

{ 

USHORT i ; 

/* Loop with four iterations */ 
for(i=l; i<5; i++) 

{ 

printf ("In Thread2, i is now %d\n'\ i); 

/* Sleep to relinquish time slice to main thread */ 

DosSl eep(SLEEPSHORT) ; /* Sleep interval */ 

} 

DosExi t { EXI T_THREAD , /* Action code - end a thread */ 

RETURN_CODE) ; /* Return code */ 

> 


main() 

{ 

TID ThreadID; 

SEL ThreadStackSel ; 

PBYTE StackEnd; 

USHORT rc; 

/** Allocate segment for thread stack; make pointer to end of stack. **/ 
/** We must allocate a segment in order to preserve segment protection **/ 
/** for the thread. **/ 

rc = DosAllocSeg(SEGSIZE, /* Number of bytes requested */ 

&ThreadStackSel , /* Segment selector (returned) */ 

ALLOCFLAGS); /* Allocation flags - no sharing */ 

StackEnd = MAKEP(Thread$tackSel , SEGSIZE-1); 

/** Start Thread2 **/ 

if (! (rc=DosCreateThread((PFNTHREAD) Thread2, /* Thread address */ 

&ThreadID, /* Thread ID (returned) */ 

StackEnd))) /* End of thread stack */ 
printf("Thread2 created. \n n ); 

/* Sleep to relinquish time slice to Thread2 */ 
if (! (DosSl eep(SLEEPSHORT) ) ) /* Sleep interval */ 

printf( "Slept a little to let Thread2 execute.\n"); 

/***** Suspend Thread2, do some work, then resume Thread2 *****/ 
if(!(rc=DosSuspendThread (ThreadID))) /* Thread ID */ 

print f ("Thread2 SUSPENDED. \n") ; 

printf ("Perform work that will not be interrupted by Thread2.\n u ); 
if(!(rc=DosResumeThread(ThreadID))) /* Thread ID */ 

printf ("Thread2 RESUMED. \n") ; 
printf ("Now we may be interrupted by Thread2.\n") ; 

/* Sleep to allow Thread2 to complete */ 

DosSl eep(SLEEPLONG) ; /* Sleep interval */ 

} 


/* Thread identification */ 

/* Segment selector for thread stack */ 
/* Ptr. to end of thread stack */ 
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FAPI 


DosRmDir - 
Remove Subdirectory 


This call removes a subdirectory from the specified disk. 


DosRmDir (DirName, Reserved) 

Parameters 

DirName ( PSZ ) - input 

Address of the fully qualified path name of the subdirectory being removed. 

Reserved (ULONG) - input 

Reserved must be set to zero. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

2 ERROR_FlLE_NOT_FOUND 

3 ERROR_PATH_NOT_FOUND 

5 ERROR_ACCESS_DENIED 

16 ERROR_CURRENT_DIRECTORY 

26 ERROR_NOT_DOS_DISK 

87 ERROR_INVALID_PARAMETER 

108 ERROR_DRIVE_LOCKED 

206 ERROR_FILENAMEJEXCED_RANGE 

Remarks 

The subdirectory must be empty, which means it cannot contain hidden files or directory entries other 
than the V and entries. Files can be deleted with DosDelete. 

The root directory and current directory cannot be removed. 

C Language 

#def i ne INCL_DOSFILEMGR 

USHORT rc = DosRmDir (Oi rName, Reserved); 

PSZ DirName; /* Directory name string */ 

ULONG 0; /* Reserved (must be zero) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosRmDir: FAR 
INCL_DO$FILEMGR EQU 1 

PUSH® ASCI IZ DirName ; Directory name string 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosRmDir 

Returns WORD 
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DosScanEnv - 

Scan an Environment Segment 


This call scans (searches) an environment segment for an environment variable. 


DosScanEnv (EnvVarName, Resu [(Pointer) 


Parameters 

EnvVarName (PSZ) - input 

Address of the name of the environment variable. Do not include a trailing since this is not part 
of the name. 

ResuItPoEnter (PSZ FAR *) — output 

Address where the system returns the pointer to the environment string. ResultPointer points to the 
first character of the string that is the value of the environment variable and can be passed directly 
into DosSearchPath. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

203 E R ROR_EN W A R_NOT_F O U N D 

Remarks 

Assume that the process' environment contains: 

" DPATH=c : \sysdi r ; c : \1 i bdi r” 

I- ResultPointer points here after the 

following call to DosScanEnv: 

DosScanEnv ( “DPATH 11 , &Resul tPoi nter) ; 

As noted above, ResultPointer points to the first character of the value of the environment variable. 

C Language 

Idefine INCLJ50SQUEUES 

USHORT rc = DosScanEnv (EnvVarName, ResultPointer); 

PSZ EnvVarName; /* Environment variable name string */ 

PSZ FAR * ResultPointer; /* Search result pointer (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosScanEnv : FAR 
INCL.DOSQUEUES EQU 1 

PUSH? ASCIIZ EnvVarName ; Environment variable name string 
PUSH? DWORD ResultPointer ; Search result pointer (returned) 

CALL DosScanEnv 

Returns WORD 
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DosScanEnv - 
Scan an Environment Segment 

Example 

The following example scans the environment segment for the PATH variable and prints its vaiue. It then 
searches the path given by inserting the current directory Into the value of the PATH variable for the file 
named "cmd.exe", and prints the full filename. 

Idefine INCLJJOS 
#include <os2.h> 

#define ENVVARNAME "PATH" /* Environment variable name */ 

fdefine FILENAME "cmd.exe" /* File for which to search */ 

Idefine SEARCH_CUR_DI RECTORY 0x03 /* Search control - current dir., */ 

/* then environment variable */ 

mai n ( ) 

{ 

PSZ FAR ^Result Pointer; /* Environment scan result pointer (returned) */ 

BYTE ResultBuffer[128] ; /* Path search result (returned) */ 

USHORT rc; /* return code */ 

/** Scan environment segment for PATH; notice the far-string pointer **/ 

/** specification ( H %Fs”) used to print. **/ 

if ( I (rc-DosScanEnv (ENVVARNAME, /* Environment variable name */ 

&Resu It Pointer))) /* Scan result pointer (returned) */ 
printf ("%s is VFs\n", ENVVARNAME. ResultPointer) ; 

/** Search current directory + PATH variable for "cmd.exe" **/ 

if (! (rc=DosSear chPath(SEARCH_CURJ) I RECTORY, /* Search control vector */ 

ENVVARNAME, /* Search path reference string */ 

FILENAME, /* File name string */ 

ResultBuffer, /* Search result (returned) */ 

sizeof(ResultBuffer)))) /* Length of search result */ 
printf ("Found desired file — %s\n", ResultBuffer); 

} 


Chapter 2. Control Program Function Calls 2-295 



DosSearchPath - 
Search Path for File Name 


This call provides a general path search mechanism that allows applications to find files residing along 
paths. The path string may come from the process environment, or be supplied directly by the caller 


DosSearchPath (Control, PathRef, FlleName, ResultBuffer, Result Buff erLen) 


Parameters 

Control ( USHORT) - input 

A word bit vector that controls the behavior of DosSearchPath. 

Bit Description 

15-3 Reserved bits, must be zero. 

2 Ignore network errors bit. The Ignore Network Errors Bit controls whether the search 

will abort if it encounters a network error or will continue the search with the next 
element. This allows one to place network paths in the PATH variable and be able to 
find executables in components of the PATH variable even if the network returns an 
error, for example, if a server is down. If the Ignore Network Errors Bit = 0, 
DosSearchPath will abort the search if it encounters an error from the network. If the 
Ignore Network Errors Bit = 1, DosSearchPath will continue on the search if it 
encounters network errors. 

1 Path source bit. The path source bit determines how DosSearchPath interprets the 

PathRef argument. 

0 = The PathRef points to the actual search path. The search path string may be any- 
where in the calling process’s address space. Therefore, It may be in the environment, 
but is not required. 

1 = The PathRef points to the name of an environment variable in the process environ- 
ment, and that environment variable contains the search path. 

0 Implied current bit. The implied current bit controls whether the current directory is 

implicitly on the front of the search path. 

0 = DosSearchPath only searches the current directory if it appears in the search path. 

1 = DosSearchPath searches the current working directory before it searches the direc- 
tories in the search path. 

For example, implied current bit = 0 and path = “.\;a;b" is equivalent to implied current 
bit = 1 and path = "a;b". 

PathRef ( PSZ ) - input 

Address of the path. If the path source bit of control = 0, PathRef is the search path that may be 
anywhere in the caller’s address space. 

A search path consists of a sequence of paths separated by a semicolon (;). It is a single ASCIIZ 
string. The directories are searched in the order they appear in the path. 

If the path source bit of control = 1, PathRef is the name of an environment variable, that contains the 
search path. 

A search path consists of a sequence of paths separated by It is a single ASCIIZ string. The 
directories are searched in the order they appear in the path. Paths that contain “;"s should be 
quoted. For example: 

"c:\this is ; one directory path";thisisanother 

Environment variable names are simply strings that match name strings in the environment. The 
equal (=) sign is not part of the name. 
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DosSearchPath - 
Search Path for File Name 


FileName (PSZ) - input 

Address of the ASCIIZ file name. It may contain global file name characters. If FileName does 
contain global file name characters, they remain in the result path returned in ResultBuffer. This 
allows applications like CMD.EXE to feed the output directly to DosFindFirst. If there are no global 
file name characters in FileName, the resulting path returned in ResultBuffer is a full qualified name, 
and may be passed directly to DosOpen, or any other system call. 

ResultBuffer (PBYTE) - output 

Address of the pathname of the file, if found. If FileName is found in one of the directories along the 
path, its full pathname is returned in ResultBuffer (with global file name characters from FileName 
left in place.) Do not depend on the contents of ResultBuffer being meaningful if DosSearchPath 
returns a non-zero return code. 

ResultBufferLen ( USHORT) - input 

Length, in bytes, of the ResultBuffer. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERRORJNVALID_FUNCTION 

2 error!file_not_found 

87 ERROR_INVALID_PARAMETER 

111 ERROR_BUFFER_OVERFLOW 

203 ERROR_ENWAR_NOT_FOUND 

Remarks 

PathRef always points to an ASCIIZ string. Let DPATH be an environment variable in the environment 
segment of the process. 

t, DPATH=c:\sysdir;c:\init ,l /* in the environment */ 

The following two code fragments are equivalent: 

DosScanEnv ("DPATH", &PathRef); 

DosSearchPath (0, /* Path Source Bit = 0 */ 

PathRef, "myprog.ini ", fcResultBuffer, ResultBufLen) ; 

DosSearchPath(2, /* Path Source Bit = 1 */ 

"DPATH", "myprog.ini", SResultBuffer, ResultBufLen); 

They both use the search path stored as DPATH in the environment segment In the first case, the appli- 
cation uses DosScanEnv to find the variable: in the second case DosSearchPath calls DosScanEnv for the 
application. 

DosSearchPath does not check for consistency or formatting on the names. It does a DosFindFirst on a 
series of names it constructs from PathRef and FileName. 

To determine the size of the returned path name, the ResultBuffer must be scanned for the ASCIIZ termi- 
nator. 

DosQSyslnfo must be used by an application to determine the maximum path length supported by OS/2. 
The returned value should be used to dynamically allocate buffers that are to be used to store paths. 
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DosSearchPath - 
Search Path for File Name 


C Language 

#define INCLJOSQUEUES 

USHORT rc = DosSearchPath (Control , PathRef, FileName, Resul tBuffer, 

ResultBufferLen) ; 

USHORT Control; /* Function control vector */ 

PSZ PathRef; /* Search path reference string */ 

PSZ FileName; /* File name string */ 

PBYTE Resul tBuffer; /* Search result buffer (returned) */ 

USHORT ResultBufferLen; /* Search result buffer length */ 

USHORT rc; /* return code */ 


Assembler Language 

EXTRN DosSearchPath: FAR 
INCL_DOSQUEUES EQU 1 

PUSH WORD Control ; Function control vector 

PUSH® ASCI IZ PathRef ; Search path reference string 

PUSH® ASCI IZ FileName ;File name string 

PUSH® OTHER Resul tBuffer ; Search result buffer (returned) 

PUSH WORD ResultBufferLen ; Search result buffer length 

CALL DosSearchPath 

Returns WORD 


Example 

The following example scans the environment segment for the PATH variable and prints its value. It then 
searches the path given by inserting the current directory into the value of the PATH variable for the file 
named "cmd.exe", and prints the full filename. 

Idefine INCL_D0S 
linclude <os2.h> 

#define ENVVARNAME “PATH" /* Environment variable name */ 

#define FILENAME "cmd.exe" /* File for which to search */ 

#define SEARCH_CUR_D I RECTORY 0x03 /* Search control - current dir., */ 

/* then environment variable */ 

main() 

{ 

PSZ FAR ^Result Pointer; /* Environment scan result pointer (returned) */ 

BYTE Resul tBuffer [128]; /it Path search result (returned) it/ 

USHORT rc; /it return code */ 

/itit Scan environment segment for PATH; notice the far-string pointer **/ 

/itit specification (“%Fs") used to print. **/ 

if (!{rc=DosScanEnv (ENVVARNAME, /it Environment variable name */ 

&ResultPointer))) /* Scan result pointer (returned) it/ 
printf ("%s is %Fs\n\ ENVVARNAME, Result Pointer); 

/** Search current directory + PATH variable for "cmd.exe" **/ 

if (! (rc=DosSearchPath(SEARCH_CUR_DIRECTORY, /* Search control vector it/ 

ENVVARNAME, /* Search path reference string */ 

FILENAME, /* File name string */ 

Resul tBuffer, /it Search result (returned) */ 

sizeof (Resul tBuffer)))) /it Length of search result */ 
printf (“Found desired file — %s\n", Resul tBuffer) ; 
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FAPI 


DosSelectDisk - 
Select Default Drive 


This call selects the drive specified as the default drive for the calling process. 


DosSelectDisk (DrlveNumber) 


Parameters 

DrlveNumber ( USHORT) — input 

New default drive number, where 1 = A and 2 = B and so on. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

15 ERROR_INVALID_DRIVE 

C Language 

Idefine INCL_DOSFILEMGR 

USHORT rc = DosSelectDisk (Dri veNumber); 

USHORT Dri veNumber; /* Default drive number */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSelectDi sk:FAR 
INCL.DOSFILEMGR EQU 1 

PUSH WORD Dri veNumber ;Default drive number 
CALL DosSelectDisk 

Returns WORD 
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DosSelectSession - 
Select Foreground Session 


This call allows a parent session to switch one of its child sessions to the foreground. 


DosSelectSession (SessID, Reserved) 


Parameters 

SessID ( USHORT) — input 

ID of the session to be switched to the foreground. The values are their meanings are: 

Value Definition 

0 Switch the caller (the parent session) to the foreground. 

^0 Switch the child session to the foreground. The nonzero value specified for SessID must 

have been returned by a previous DosStartSession request. 

Reserved ( ULONG ) - input 
A DWord of 0. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

369 ERROR_SMG_INVALID_SESSIONJD 

418 ERROR_SMGJNVALID_CALL 

451 ERROR_SMG_SESSION_NOT_FOREGRND 

452 ERROR_SMGSESSION_NOT_PARENT 

459 ERROR_SMG_BAD_RESERVE 

Remarks 

DosSelectSession can be issued by a parent session to select only itself or a child session. It cannot be 
used to select a grandchild session. The child session must have been started by the caller with a 
request to DosStartSession, specifying "Related = 1." Sessions started as independent sessions cannot 
be selected with this call. 

When DosSelectSession is issued, the session is brought to the foreground only if the parent session or 
one of its descendant sessions is executing in the foreground. Otherwise, 
ERROR_SMG_SESSION_NOT_FOREGRND is returned. 

C Language 

ifdefine INCL_DOSSESMGR 

USHORT rc = DosSelectSession(SessID, Reserved); 

USHORT SessID; /* Session ID */ 

ULONG 0; /* Reserved (must be zero) */ 

USHORT rc; /* return code 4c/ 

Assembler Language 

EXTRN DosSelectSession: FAR 
INCL.DOSSESMGR EQU 1 

PUSH WORD SessID ; Session ID 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosSelectSession 

Returns WORD 
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DosSemClear - 
Clear Semaphore 


This call unconditionally clears a semaphore. If any threads were blocked on the semaphore, they are 
restarted. 


DosSemClear (SemHandle) 


Parameters 

SemHandle (HSEM) — input 

Reference to the semaphore. 

For a system semaphore, this reference is the handle returned by a DosCreateSem or DosOpenSem 
request that granted the requesting thread access to the semaphore. 

For a RAM semaphore, this reference is the address of a doubleword of storage, allocated and ini- 
tialized to zero by the application. This sets the semaphore as unowned. Other than initializing the 
doubleword to zero, an application must not modify a RAM semaphore directly; instead it manipu- 
lates the semaphore with semaphore function calls. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

101 ERRORJEXCL_SEM_ALREADY_OWNED 

Remarks 

DosSemClear typically is used to release a semaphore obtained through DosSem Request. DosSemClear 
also is used with the semaphore signaling functions DosSemSetWait, DosSemWait, and DosMuxSemWait. 

If the semaphore is an exclusive system semaphore, it has a use count associated with it, which is incre- 
mented by a DosSemRequest and decremented by a DosSemClear. The semaphore is not actually 
cleared and made available to the next thread that wants to access the resource until the semaphore has 
been cleared the same number of times it has been requested. This means that exclusive system 
semaphores can be used in recursive routines. When the use count is 0, the semaphore is available to 
be claimed by the next user of the protected resource. 

Normally, DosSemClear cannot be issued against a system semaphore owned by another process unless 
the NoExclusive option is set by the DosCreateSem request that created the semaphore. However, at 
interrupt time any thread may clear an exclusively owned semaphore. 

C Language 

Idefine INCL.DOSSEMAPHORES 
USHORT rc = DosSemClear (SemHandle); 

HSEM SemHandle; /* Semaphore handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN OosSemClear:FAR 
INCLJOSSEMAPHORES EQU 1 

PUSH DWORD SemHandle ; Semaphore handle 

CALL DosSemClear 

Returns WORD 
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DosSemClear - 
Clear Semaphore 


Example 

The following example illustrates the serialization of access to a shared resource between threads of the 
same process. The program creates a nonexclusive system semaphore named resource.sem, requests 
access to the semaphore, clears it, and finally closes the semaphore. For an illustration of notification of 
events, see the example given In DosOpenSem, DosSemSet, or DosSemWait. 

#define INCL_DOSSEMAPHORES 

#include <os2.h> 

Idefine SEMJJAME U \\SEM\\ resource. sera" /* Semaphore name */ 

#define TIMEOUT 150OL /* Timeout (in milliseconds) */ 


main() 

{ 

KSEM SemHandle; 

USHORT rc; 

/* Note: the semaphore could have been created by another */ 

/* thread. */ 

Do$CreateSem(CSEM_PUBLIC, /* Ownership - nonexclusive ief 

&SemHandle, /* Semaphore handle (returned) */ 

SEMJIAME); fie Semaphore name */ 

if (I (rc = DosSemRequest (SemHandle, fie Semaphore Handle */ 

TIMEOUT))) fie Timeout Period */ 

{ 

fie Semaphore obtained; resource may now be used. */ 
fie Clear the semaphore after using resource. */ 
if (DosSemClear (SemHandle)) 

{ 

fie Semaphore exclusively owned by another process — ief 
/* cannot clear now. */ 

} 

} 

else 

{ 

fie Semaphore not obtained: error processing (i.e. switch on rc) ief 

) 

fie Semaphore no longer needed; close it ief 
i f (DosCl oseSem ( SemHandl e) ) 

{ 

fie Semaphore is still set — cannot close now ief 

} 
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DosSemRequest - 
Request Semaphore 


This call obtains a semaphore and sets the semaphore as owned by the thread that requested It. 


Do8Sem Request (SemHandle, Timeout) 


Parameters 

SemHandle (HSEM) - Input 

Reference to the semaphore. 

For a system semaphore, this reference Is the handle returned by a DosCreateSem or DosOpenSem 
request that granted the requesting thread access to the semaphore. 

For a RAM semaphore, this reference is the address of a doubleword of storage, allocated and ini- 
tialized to zero by the application. This sets the semaphore as unowned. Other than initializing the 
doubleword to zero, an application must not modify a RAM semaphore directly; instead it manipu- 
lates the semaphore with semaphore function calls. 

Timeout (LONG) - input 

Action taken by the requesting thread when the semaphore is owned by another thread. The values 
that can be specified are: 

Value Definition 

—1 The requesting thread waits indefinitely for the semaphore to be cleared. 

0 The requesting thread returns immediately. 

> 0 The requesting thread waits the indicated number of milliseconds for the semaphore to 

be cleared before resuming execution. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

95 ERRORJNTERRUPT 

100 ERROR_TOO_MANY_SEMAPHORES 

105 ERROR_SEM_OWNER_DIED 

121 E R ROR_SEM_TI M EOUT 

Remarks 

Typically, DosSemRequest is called to set a semaphore for the purpose of accessing a protected 
resource. DosSemRequest checks the status of the semaphore. If the semaphore is not set (that is, not 
owned) by another thread, DosSemRequest sets the semaphore as owned by the current thread and 
returns immediately to the caller. 

If the semaphore is already owned by another thread, DosSemRequest optionally can block the 
requesting thread until the semaphore becomes available. The unblocking of a thread blocked by a 
DosSemRequest is level-triggered. That is, DosSemRequest does not return until the semaphore 
remains clear long enough for the affected thread to be redispatched and successfully claim the 
semaphore. Thus, if a number of threads are blocked indefinitely on DosSemRequest calls for the 
semaphore, only the thread that sets the semaphore is actually unblocked. If a milliseconds value is 
specified for the Timeout parameter, this places an upper limit on the amount of time the requesting 
thread remains blocked, waiting for the semaphore to become available. 

When a thread no longer requires the protected resource, it issues DosSemClear to clear the semaphore, 
so another thread may claim it with a successful DosSemRequest. If the semaphore is an exclusive 
system semaphore, it has a use count associated with it, which is incremented by a DosSemRequest and 
decremented by a DosSemClear. The semaphore is not actually cleared and made available to the next 
thread that wants to access the resource until the semaphore has been cleared the same number of 
times it has been requested. This means that exclusive system semaphores can be used in recursive 
routines. When the use count is 0, the semaphore is available to be claimed by the next user of the pro- 
tected resource. 
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DosSemRequest - 
Request Semaphore 


If a process terminates while owning a nonexclusive system semaphore, ERROR_SEM_OWNER_DIED is 
returned to the thread that next gets the semaphore through DosSemRequest. That thread takes steps to 
ensure the integrity of the resource. The thread can release the resource by issuing a DosSemClear, or 
it can reset the ERROR_SEM_OWNER_DIED return code condition flagged in the semaphore data struc- 
ture. 

Note: To request a Fast-Safe RAM semaphore, a thread calls DosFSRamSemRequest. 

C Language 

#define INCL_DOSSEMAPHORES 

USHORT rc = DosSemRequest (SemHandle, Timeout); 

HSEM SemHandle; /* Semaphore handle */ 

LONG Timeout; /* Timeout (in milliseconds) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSemRequest; FAR 
I NCL_DOSSEMAPHORES EQU 1 

PUSH DWORD SemHandle ; Semaphore handle 

PUSH DWORD Timeout ; Timeout (in milliseconds) 

CALL DosSemRequest 

Returns WORD 

Example 

The following example illustrates the serialization of access to a shared resource between threads of the 
same process. The program creates a nonexclusive system semaphore named resource.sem, requests 
access to the semaphore, clears it, and finally closes the semaphore. For an illustration of notification of 
events, see the example given in DosOpenSem, DosSemSet, or DosSemWait. 
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DosSem Request - 
Request Semaphore 


#de fine INCL_DOSSEMAPHORES 
finclude <os2.h> 

Idefine SEM_NAME "WSEMWresource.sem" /* Semaphore name */ 

Idefine TIMEOUT 1500L /* Timeout (in milliseconds) */ 


main() 

{ 

HSEM SemHandle; 
USHORT rc; 


/* Note: the semaphore could have been created by another */ 
/* thread. */ 


DosCreateSem(CSEM_PUBLIC, fie Ownership - nonexclusive ief 

&SemHandle f /* Semaphore handle (returned) */ 

SEM_NAME); fie Semaphore name ief 

if(!(rc = DosSemRequest (SemHandle, fie Semaphore Handle */ 

TIMEOUT))) /★ Timeout Period ief 

{ 


fie Semaphore obtained; resource may now be used, ief 
fie Clear the semaphore after using resource. ief 

i f (DosSemCl ear (SemHandl e) ) 

{ 

fie Semaphore exclusively owned by another process — */ 
fie cannot clear now. ief 

} 

> 

else 

{ 

fie Semaphore not obtained: error processing (i.e. switch on rc) ief 

} 

fie Semaphore no longer needed; close it ief 
i f ( DosCl oseSem (SemHandl e) ) 

{ 

fie Semaphore is still set — cannot close now ief 

} 
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DosSemSet - 

Set Semaphore Owned 


This call unconditionally sets a semaphore; that is, it sets the semaphore whether or not it is already set 


DosSemSet (SemHandle) 


Parameters 

SemHandle ( HSEM ) - input 

Reference to the semaphore. 

For a system semaphore, this reference is the handle returned by a DosCreateSem or DosOpenSem 
request that granted the requesting thread access to the semaphore. 

For a RAM semaphore, this reference is the address of a doubleword of storage, allocated and ini- 
tialized to zero by the application. This sets the semaphore as unowned. Other than initializing the 
doubleword to zero, an application must not modify a RAM semaphore directly; instead it manipu- 
lates the semaphore with semaphore function calls. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

100 ERROR_TOO_MANY_SEMAPHORES 

103 ERROR JTOO_M AN Y_SEM_REQUESTS 

Remarks 

DosSemSet usually is not required in a resource control environment using DosSemRequest and 
DosSemClear. It typically is used in a signaling environment implemented with DosSemWait, 
DosMuxSemWait, and DosSemClear. These function calls are used to block one or more threads on a set 
semaphore and awaken them when an event occurs. 

DosSemSet cannot be issued against a system semaphore that is owned by another thread, unless the 
NoExclusive option was set in the original DosCreateSem request. 


C Language 

#define INCLJJOSSEMAPKORES 
USHORT rc = DosSemSet (SemHandl e) ; 


HSEM 

SemHandle; 

/ * Semaphore handle */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosSemSet: FAR 
I NCL_DOSSEMAPHORES EQU 1 

PUSH DWORD SemHandle ; Semaphore handle 
CALL DosSemSet 

Returns WORD 
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DosSemSet - 
Set Semaphore Owned 


Example 

The following example Illustrates the notification of an event between threads of different processes. 
Processl creates a nonexclusive system semaphore named process! .sem and sets it It then invokes 
process2 to run asynchronously. Processl then waits, with a time out of 4.5 seconds, for process2 to 
open the semaphore and clear it, thereby notifying processl to resume. Notice that there is a small pos- 
sibility of processes missing the notification because process2 may clear the semaphore before 
process! issues DosSemWait. See the example for DosSemSetWait for an alternative that would correct 
this. 

/* process l.c */ 

Idefine INCL_DOSSEMAPHORES 
#define INCL_DOSPROCESS 

linclude <os2.h> 

Idefine SEM_NAME "WSEMWprocessl.sem" /* Semaphore name */ 

Idefine TIMEOUT 4500L /* Timeout period */ 

Idefine START_PROGRAM "process2.exe" /* Name of program file */ 

main() 

{ 

HSEM SemHandle; 

CHAR Ob j Fail [50]; 

PSZ Args; 

PSZ Envs; 

RESULTCODES ReturnCodes; 

USHORT rc; 

printf ("Processl now running. \n"); 

rc - DosCreateSem(CSEM_PUBLIC, /* Ownership - nonexclusive */ 

&SemHandle. /* Semaphore handle (returned) */ 

SEMJIAME); /* Semaphore name string */ 

printf ("Processl. sem created; return code is %d \n", rc); 

/*** SET the semaphore. ***/ 

if ((rc = DosSemSet (SemHandle))) /* Semaphore handle */ 

/****************************************/ 

{ 

/* Cannot set semaphore — error processing */ 

} 

/* Start a separate process */ 

if (! (DosExecPgm(0bjFai1 , /* Object name buffer */ 

si zeof (Obj Fail), /* Length of obj. name buffer */ 

EXEC_ASYNC, /* Execution flag - asynchronous */ 

Args, /* Ptr. to argument string */ 

Envs, /* Ptr. to environment string */ 

SReturnCodes, /* Ptr. to resultcodes struct. */ 

START_PROGRAM))) /★ Name of program file */ 

printf ("Process2 started. Processl will try to wait for notification. \n"); 

/*** WAIT for a notification from process2 on processl. sem ***/ 
if((rc = DosSemWait (SemHandle, /* Semaphore handle */ 

TIMEOUT))) /* Timeout period */ 

/****************************************/ 

{ 

/* No notification (either interrupt or timeout); error processing */ 

} 

else 

{ 

/* Notification received. Normal processing */ 

printf ("Process2 cleared semaphore; processl running again. \n“); 

} 

} 
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DosSemSet - 

Set Semaphore Owned 


/* proces$2.c */ 

#def i ne INCL_DOSSEMAPHORES 
linclude <o$2.h> 

Idefine SEM_NAME "\\SEM\\processl.sem“ /* Semaphore name */ 

main() 

{ 

HSEM SemHandle; 

USHORT rc; 

/* Obtain access to semaphore created by process 1 via OPEN */ 
if ((rc=DosOpenSem(&SemHandle, /* Semaphore handle (returned) */ 

S EM_NAME ) ) ) /* Semaphore Name */ 

/****************************************/ 

{ 

/* Could not open -- error processing (switch on rc). */ 

} 

else 

{ 

/* Opened semaphore; normal processing. Clear semaphore when done, if/ 
printf(" Semaphore OPENED. \n“); 

if (! (rc=DosSemCl ear (SemHandle))) /if Semaphore handle */ 

printf( “Semaphore CLEARED. \n“); 

} 

} 
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DosSemSetWait - 

Set Semaphore and Wait for Next Clear 


This call sets a semaphore if the semaphore is not already set and waits until another thread clears the 
semaphore with a DosSemClear call. 


DosSemSetWait (SemHandle, Timeout) 


Parameters 

SemHandle (HSEM) - input 

Reference to the semaphore. 

For a system semaphore, this reference is the handle returned by a DosCreateSem or DosOpenSem 
request that granted the requesting thread access to the semaphore. 

For a RAM semaphore, this reference is the address of a doubleword of storage, allocated and ini- 
tialized to zero by the application. This sets the semaphore as unowned. Other than initializing the 
doubleword to zero, an application must not modify a RAM semaphore directly; instead it manipu- 
lates the semaphore with semaphore function calls. 

Timeout (LONG) - input 

Action taken by the requesting thread when the semaphore is set. The values that can be specified 
are: 

Value Definition 

-1 The requesting thread waits indefinitely for the semaphore to be cleared. 

0 The requesting thread returns immediately. 

> 0 The requesting thread waits the indicated number of milliseconds for the semaphore to 

be cleared before resuming execution. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

95 ERRORJNTERRUPT 

101 ERROR_EXCL_SEM_ALREADY_OWNED 

103 ERROR_TOO_MANY_SEM_REQUESTS 

121 ERROR_SEM_TIMEOUT 

Remarks 

DosSemSetWait combines the functions of DosSemSet and DosSemWait and is used when there is a 
chance the semaphore may be be cleared by a thread that gets an intervening time slice between calls 
by the current thread to set the semaphore and wait until it is cleared. 

A DosSemSetWait request differs from a DosSemWait request in that it ensures that the semaphore is set 
so that it can block on it. Issuing DosSemWait on a semaphore that has been cleared has no effect. 
Instead of blocking, the caller continues to execute. 

The unblocking of a thread blocked by a DosSemSetWait is level-triggered. That is, DosSemSetWait does 
not return until the semaphore remains clear long enough for the affected thread to be redispatched and 
determine that the semaphore is clear. 

DosSemSetWait cannot be issued against a system semaphore owned by another thread unless the 
NoExclusive option was selected on the DosCreateSem request that created the semaphore. 
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DosSemSetWait - 

Set Semaphore and Wait for Next Clear 


C Language 

^define INCL_DOSSEMAPHORES 

USHORT rc = DosSemSetWait (SemHandle, Timeout); 


HSEM 

SemHandle; 

/* Semaphore handle */ 

LONG 

Timeout; 

/* Timeout (in milliseconds) */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosSemSetWait: FAR 
INCL_DOS$EMAPHORES EQU 1 

PUSH DWORD SemHandle Semaphore handle 

PUSH DWORD Timeout ; Timeout (in milliseconds) 

CALL DosSemSetWai t 

Returns WORD 


Example 

The following example Illustrates the notification of an event between threads of different processes. 
Processl creates a nonexclusive system semaphore named process'! .sem. It then invokes process2 to 
run asynchronously. Finally, processl sets the semaphore and waits, with a timeout of 4.5 seconds, for 
process2 to open the semaphore and clear it. Processl resumes after this clearance. The following 
example is different from the one given for DosSemSet and DosSemWait only in that the set and wait 
functions are performed in one atomic step, via DosSemSetWait. Hence, In the following example, there 
is no possibility for processl to miss the notification because of a premature clear by process2. 
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DosSemSetWait - 

Set Semaphore and Wait for Next Clear 

/* process l.c */ 

Idefine INCL DOSSEMAPHORES 
#deftne INCL_DOSPROCESS 

linclude <os2.h> 

Idefine SEM_NAME w \\SEM\\processl.sem” /* Semaphore name */ 

Idefine TIMEOUT 4500L /* Timeout period */ 

Idefine START_PRDGRAM "process2.exe" /* Name of program file */ 

main() 

{ 

HSEM SemHandle; 

CHAR Obj Fail [50]; 

PSZ Args; 

PSZ Envs; 

RESULTCODES ReturnCodes; 

USHORT rc; 

printf ("Processl now running. \n"); 

rc - DosCreateSem(CSEM_PUBLIC, /* Ownership indicator */ 

&SemHandle, /* Semaphore handle (returned) */ 

SEM_NAME); /* Semaphore name string */ 

printf (“Process l.sem created; return code is %d \n", rc); 

/* Start a separate process */ 

if (!(DosExecPgm (Obj Fail t /* Object name buffer */ 

sizeof(ObjFail), /* Length of obj. name buffer */ 

EXEC_ASYNC, /* Execution flag - asynchronous */ 

Args, /* Ptr. to argument string */ 

Envs, /* Ptr. to environment string */ 

&ReturnCodes, /* Ptr. to resultcodes struct. */ 

START_PROGRAM))) /* Name of program file */ 

printf ("Process2 started. Processl will try to wait for notification. \n"); 

/************* SET semaphore and WAIT for a notification ************/ 

/************* from process2 on processl. sem ************/ 

if ((rc = DosSemSetWait (SemHandle, /* Semaphore handle */ 

TIMEOUT))) /* Timeout period */ 

/****************************★***********/ 

{ 

/* No notification (either interrupt or timeout); error processing */ 

} 

else 

{ 

/* Notification received. Normal processing */ 

print f(“Process2 cleared semaphore; processl running again. \n‘‘); 

} 

} 
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DosSemSetWait - 

Set Semaphore and Wait for Next Clear 


/* process2.c */ 

Idefine INCL_DOSSEMAPHORES 
linclude <os2.h> 

Idefine SEM_NAME "\\SEM\\processl.sem" /* Semaphore name */ 

main() 

{ 

HSEM SemHandle; 

USHORT rc; 


} 


/* Obtain access to semaphore created by processl via OPEN */ 
if((rc=DosOpenSem(&SemHandle, /* Semaphore handle (returned) */ 

SEM_NAME) ) ) /* Semaphore Name */ 


{ 


/* Could not open -- error processing (switch on rc). */ 

} 


else 


{ 


/* Opened semaphore; normal processing. Clear semaphore when done. */ 
print f ("Semaphore OPENED. \n“); 

if(!(rc=DosSemCl ear (SemHandle))) /* Semaphore handle */ 
printf ("Semaphore CLEARED. \n“); 

} 
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DosSemWait - 
Wait for Semaphore To Clear 


This call blocks the current thread until an indicated semaphore clears t but does not establish ownership 
of the semaphore. 


DosSemWait (SemHandie, Timeout) 


Parameters 

SemHandie ( HSEM ) - input 
Reference to the semaphore. 

For a system semaphore, this reference is the handle returned by a DosCreateSem or DosOpenSem 
request that granted the requesting thread access to the semaphore. 

For a RAM semaphore, this reference is the address of a doubleword of storage, allocated and ini- 
tialized to zero by the application. This sets the semaphore as unowned. Other than initializing the 
doubleword to zero, an application must not modify a RAM semaphore directly; instead it manipu- 
lates the semaphore with semaphore function calls. 

Timeout (LONG) - input 

Action taken by the requesting thread when the semaphore is set. The values that can be specified 
are: 

Value Definition 

-1 The requesting thread waits indefinitely for the semaphore to be cleared. 

0 The requesting thread returns immediately. 

> 0 The requesting thread waits the indicated number of milliseconds for the semaphore to 

be cleared before resuming execution. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

95 ERRORJNTERRUPT 

121 ERROR_SEM_TIMEOUT 

Remarks 

The unblocking of a thread blocked by a DosSemWait is level-triggered. That is, DosSemWait does not 
return until the semaphore remains clear long enough for the affected thread to be redispatched and 
determine that the semaphore is clear. 

When an application needs to guarantee that another event has occurred before continuing, it calls 
DosSemSetWait. DosSemSetWait combines the functions of DosSemSet and DosSemWait and is used 
when there is a chance the semaphore may be cleared by a thread that gets an intervening time slice 
between calls by the current thread to set the semaphore and wait until it is cleared. Issuing 
DosSemWait on a semaphore that has been cleared has no effect; the thread continues to execute. 


C Language 

#define 1NCLJ50SSEMAPH0RES 

USHORT rc » DosSemWait (SemHandie, Timeout); 


HSEM 

SemHandie; 

/* Semaphore handle */ 

LONG 

Timeout; 

/* Timeout (in milliseconds) */ 

USHORT 

rc; 

/* return code */ 
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DosSemWait - 

Wait for Semaphore To Clear 


Assembler Language 

EXTRN DosSemWait: FAR 
INCl.DOSSEMAPHORES EQU 1 

PUSH DWORD SemHandle ; Semaphore handle 

PUSH DWORD Timeout ; Timeout (in milliseconds) 

CALL DosSemWait 

Returns WORD 

Example 

The following example illustrates the notification of an event between threads of different processes. 
Processl creates a nonexclusive system semaphore named process'!. sem and sets it. It then invokes 
process2 to run asynchronously. Processl then waits, with a timeout of 4.5 seconds, for process2 to open 
the semaphore and clear it, thereby notifying processl to resume. Notice that there is a small possibility 
of processl 's missing the notification because process2 may clear the semaphore before processl 
issues DosSemWait. See the example for DosSemSetWait for an alternative that would correct this. 
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DosSemWait - 
Wait for Semaphore To Clear 

/* processl.c */ 

Idefine INCL_00SSEMAPH0RES 
#define INCL.DOSPROCESS 

linclude <os2.h> 

#define SEM_NAME tl \\SEM\\processl.sem M /* Semaphore name */ 

#define TIMEOUT 4500L /* Timeout period */ 

Idefine START_PRQGRAM "process2.exe" /* Name of program file */ 

main() 

{ 

HSEM SemHandle; 

CHAR Ob j Fail [50]; 

PSZ Args ; 

PSZ Envs; 

RESULTCODES ReturnCodes; 

USHORT rc; 

printf( n Processl now running. \n“); 

rc = DosCreateSem(CSEM_PUBLIC. /* Ownership - nonexclusive */ 

fcSemHandle, /* Semaphore handle (returned) */ 

$EM_NAME); /* Semaphore name string */ 

printf (" Process l.sem created; return code is %d \n H , rc); 

/*** SET the semaphore. ***/ 

if((rc = DosSemSet(SemHandle))) /* Semaphore handle */ 

/ieirkieieieieieieieieieieieieieieieieieieieieieieieieieieie'kieieieieieieieieie/ 

{ 

/* Cannot set semaphore -- error processing */ 

} 

/* Start a separate process */ 

if (! ( Dos Exec Pgm( Ob j Fail , /* Object name buffer */ 

sizeof(ObjFail), /* Length of obj. name buffer */ 

EXEC_ASYNC, /* Execution flag - asynchronous */ 

Args, /* Ptr. to argument string */ 

Envs, /* Ptr. to environment string */ 

SReturnCodes , /* Ptr. to resultcodes struct. */ 

START_PROGRAM) ) ) /* Name of program file */ 

printf (“Process2 started. Process 1 will try to wait for notification. \n"); 

/*** WAIT for a notification from process2 on processl.sem ***/ 
if({rc - DosSemWait (SemHandle, /* Semaphore handle */ 

TIMEOUT))) /* Timeout period */ 

/************************* ***************/ 

{ 

/* No notification (either interrupt or timeout); error processing */ 

> 

else 

{ 

/* Notification received. Normal processing */ 

printf ("Process2 cleared semaphore; process 1 running again. \n"); 

} 

} 
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Wait for Semaphore To Clear 


/* process2.c */ 

Idefine INCL_DOSSEMAPHORES 
linclude <os2.h> 

#define SEM_NAME "WSEMWprocessl.sem" /* Semaphore name */ 

mai n () 

{ 

HSEM SemHandle; 

USHORT rc; 

/* Obtain access to semaphore created by processl via OPEN */ 
if((rc=DosOpenSem(&SetnHandle, /* Semaphore handle (returned) */ 

SEMJIAME))) /* Semaphore Name */ 

/****************************************/ 

{ 

/* Could not open — error processing (switch on rc). */ 

else 

{ 

/* Opened semaphore; normal processing. Clear semaphore when done. */ 
printf( "Semaphore OPENED. \n M ); 

if (! (rc=DosSemC1 ear (SemHandle))) /* Semaphore handle */ 

print f( “Semaphore CLEARED. \n"); 

} 

} 
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Send SIGINTR or SIGBREAK Signal 


This call sends either a SIGINTR or a SIGBREAK signal to a process within a specified process tree. 


DosSendSignal (PID, SigNumber) 

Parameters 

PID ( USHORT) - input 

Root process ID of the subtree. It is not necessary that this process be alive, but it is necessary that 
this process be a direct child process of the process that issues this call. 

SigNumber ( USHORT) - input 
Signal to send. It may be: 

Value Definition 

1 (SIGINTR) Ctrl-C 

4 (SIGBREAK) Ctrl-Break. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERROR_INVALID_FUNCTION 

156 ERROR_SIGNAL_REFUSED 

205 ERROR_NO_SIGNAL_SENT 

209 ERRORJNVALID_SIGNAL_NUMBER 

303 ERRORJNVALID_PROCID 

Remarks 

The process that receives the signal is the most distant descendant process among those processes in 
the tree that have a handler Installed for the signal. 

The process tree is searched in descending order for processes having a handler installed for the speci- 
fied signal. If there is at least one eligible process in the tree, the signal is sent to the process that is the 
most distant descendent process among the eligible processes. The selected process may have 
descendants, but none of them have the handler installed for the signal. If there is more than one most 
distant descendent eligible process, the signal is sent to one of them; which one is indeterminate. 

Presentation Manager applications may not establish signal handlers for Ctrl-C and Ctrl-Break. Estab- 
lishing a signal handler for Ctrl-C and Ctrl-Break is supported for VIO-Windowable and full-screen appli- 
cations. 

C Language 

#define 1NCL_D0SSIGNAL$ 

USHORT rc = DosSendSignal (PIO, SigNumber); 

USHORT PID; /* PID of root of subtree */ 

USHORT SigNumber; /* Signal Number to send */ 

USHORT rc; /* return code */ 


Chapter 2. Control Program Function Calls 2-317 







DosSendSignal - 

Send SIGINTR or SIGBREAK Signal 


Assembler Language 

EXTRN DosSendSignal: FAR 
INCL_DOSSIGNALS EQU 1 

PUSH WORD PID ;PID of root of subtree 

PUSH WORD SigNumber ; Signal Number to send 

CALL DosSendSignal 

Returns WORD 


Example 

The following example illustrates the use of the Ctrl-C (SIGINTR) signal to signal time-critical events. 
Processl invokes process2 t which establishes a signal handler named CtrlC_Handler() and waits, by 
blocking on a reserved RAM semaphore, for a signal from processl. A portion of process2 is immune to 
signalling. 

#de fine INCL_D0$PR0CESS 
Idefine INCLJ)OSSIGNAL$ 

linclude <os2.h> 

#define SLEEPTIME 20OL /* Sleep interval */ 

#define START_PR0GRAM "process2.exe" /* Program name */ 


main() 

{ 

CHAR ObjFailffiSO"; 

PSZ Args; 

PSZ Envs; 

RESULTCODES ReturnCodes ; 

USHORT rc; 

/* Start process2 and check its PID */ 

if (! ( Dos ExecPgm(Obj Fail , /* Object name buffer */ 

sizeof(ObjFail), /* Length of obj. name buffer */ 

EXEC_ASYNC, /* Execution flag */ 

Args, /* Ptr. to argument string */ 

Envs, /* Ptr. to environment string */ 

&ReturnCodes, /* Ptr. to resultcodes struct. */ 

START_PROGRAM) ) ) /* Name of program file */ 

printf("Process2 started. \n“ ) ; 

printf ( ,, Process2 ID is %d\n”, ReturnCodes.codeTerminate) ; 

/* Sleep to give time slice to process2 */ 

DosSleep(SLEEPTIME) ; fie Sleep interval */ 

/ *** After process2 sets signal handler, send process2 a signal ***/ 

if (! (rc = DosSendSignal (ReturnCodes.codeTerminate, /★ PID of process2 */ 
SIG_CTRLC) ) ) /* Signal to send */ 

printfC’Ctrl-C signal sent from Processl to Process2.\n“) ; 
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Send SIGINTR or SIGBREAK Signal 


/* process2.c */ 

Idefine INCL_DOSPROCESS 
Idefine INCL_DOSSIGNALS 
Idefine INCL_D0SERR0RS 

linclude <os2.h> 

Idefine SLEEPTIME 501 

Idefine TIMEOUT 50Q0L 


VOID APIENTRY CtrlC_Handler(argl, arg2) /** Define signal handler **/ 
USHQRT arglf 

USHORT arg2; 

{ 

printf (“Handler for Ctrl-C now running. \n*') ; 
return; 

} 


main() 

{ 

ULONG RamSem « OL; /* Allocate and initialize Ram Semaphore */ 

ULONG far *RamSemHandl e - &RamSem; /* Ram Semaphore handle */ 

USHORT rc; 

/* Establish signal handler */ 

i f ( ! (rc=Dos$etSi gHandl er ( (PFNSIGHANDLER) CtrlC_Handler, 

NULL, /ie Previous handler - ignored */ 

NULL, /ie Previous action - ignored */ 

$IGA_ACCEPT, /ie Request type ie/ 

SIG_CTRLC))) /ie Signal number ie/ 

print f("Process2 has set Ctrl-C handler. \n“) ; 
else 

/ie Error processing on rc ie/; 

/ie Get semaphore for first time ie/ 

if(l(rc=DosSemRequest(RamSemHandle, /ie Semaphore handle */ 

TIMEOUT))) /ie Timeout interval ie/ 

printf ( "Semaphore obtained. \n") ; 

/*** Disable and then enable signal -handling ***/ 
if(!(rc»DosHoldSignal (HLDSIG DISABLE))) /ieie Action code - disable **/ 

{ 

pri ntf ( "Si gnal 1 i ng D I SABLED . \n " ) ; 

/ie Do signal -proof work here */ 

if (! (rc-DosHoldSignal (HLDSIG_ENABLE) ) ) /ieie Action code - enable ieie/ 
pri ntf ("Signal ling ENABLED. \n“ ) ; 

} 

/ie At this point, processl may have sent a Ctrl-C signal, ie/ 

/ie Try to obtain semaphore again — resulting in Timeout, ie/ 

/ie The Timeout, however, may be interrupted by the signal, ie/ 

printf( w Process2 will now wait on a Ramsem for a while.\n"); 
if((rc=DosSemRequest(RamSemHandle, /* Semaphore handle ie/ 

TIMEOUT)) /ie Timeout interval ie/ 

ERRORJNTERRUPT) 

printf (“Process2 interrupted while waiting, rc is %d.\n", rc); 

} 
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Set Code Page 


FAPI xPM 


This call allows a process to set its code page and the session's display code page and keyboard code 
page. 


DosSetCp (CodePage, Reserved) 


Parameters 

CodePage ( USHORT) - input 

Code page identifier word that has one of the following values: 


Value 

Definition 

437 

IBM PC US 437 code page 

850 

Multilingual code page 

860 

Portuguese code page 

863 

Canadian-French code page 

865 

Nordic code page. 

Reserved ( USHORT) - input 

Reserved must be set to zero. 

rc ( USHORT) ~ 

return 

Return code descriptions are: 

0 

NO_ERROR 

5 

ERROR_ACCESS_DENIED 

13 

ERROR_INVALID_DATA 

472 

error_invalidIcode_page 

482 

ERROR_CP_SWITCH_INCOMPLETE 


Remarks 

DosSetCp allows a program to set its code page. See CONFIG.SYS and the CODEPAGE command for 
preparing code pages for the system. The first code page specified in the CODEPAGE command is the 
default system code page. The session code page of a new session is set to the default system code 
page. A session's code page can be changed by the user with the CHCP command at the command 
prompt. The process code page of a new program started from a session command prompt is set to that 
session’s code page. 

DosSetCp sets the process code page of the calling process. The code page of a process is used in a 
series of ways. First, the printer code page is set to the process code page through the file system and 
printer spooler when the process makes an open printer request. Calling DosSetCp does not affect the 
code page of a printer opened prior to the call and does not affect the code page of a printer opened by 
another process. Second, country dependent information, by default, is retrieved encoded in the code 
page of the calling process. And third, a newly created process inherits its process code page from its 
parent process. 

DosSetCp also sets, in the session to which the calling process belongs, the code page for the session's 
default logical keyboard and automatically flushes the keyboard buffer. It also sets the display code page 
for the session’s logical display. This setting of the code page for the session’s default logical keyboard 
and display overrides any previous setting by DosSetCp, DosSetProcCp, KbdSetCp, and VioSetCp by any 
process in the same session. Also see DosSetProcCp. 
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DosSetCp - 
Set Code Page 


C Language 

#define INCLJ30SNLS 

USHORT rc = DosSetCp (CodePage, Reserved); 

USHORT CodePage; /* Code page identifier */ 

USHORT 0; /* Reserved, set to zero */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSetCp; FAR 
INCLJ50SNLS EQU 1 

PUSH WORD CodePage ;Code page identifier 

PUSH WORD 0 ; Reserved (must be zero) 

CALL DosSetCp 

Returns WORD 
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Set Current Date and Time 


FAPI 


This call is used to set the date and time that are maintained by the operating system. 


DosSetDateTime (DateTIme) 


Parameters 

DateTIme ( PDATETIME ) - input 

Address of the date and time structure: 

hours (UCHAR) 

Current hour (0-23). 

minutes (UCHAR) 

Current minute (0-59). 

seconds (UCHAR) 

Current second (0-59). 

hundredths (UCHAR) 

Current hundredth of a second (0-99). 

day (UCHAR) 

Current day (1 -31). 

month (UCHAR) 

Current month (1 - 12). 

year (USHORT) 

Current year (1980-2079). 

timezone (SHORT) 

Minutes west of UTC (Universal Time Coordinate -720 to 720). 
weekday (UCHAR) 

Current day of the week. This value is ignored and is calculated from the other parameter infor- 
mation. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

327 ER ROR_TS_DATETI M E 

Remarks 

The value of timezone is the difference in minutes between the current time zone and UTC. This is a 
positive number if earlier than UTC, and negative number if it is later. For Eastern Standard Time this 
value is 300 (five hours earlier than UTC). 

To get the date and time, issue DosGetDateTime. If the application is executing in the OS/2 environment, 
it is more efficient to obtain these variables by calling DosGetlnfoSeg instead of this function. However, 
applications written to the family API cannot depend on the availability of DosGetlnfoSeg. 

Not adhering to the limits on any of the parameters results in the return code being set to rc = 327 
(ERROR_TS_DATETIME). Also, OS/2 verifies that the day is possible for the month and the year (even for 
leap year). If the day is not reasonable, OS/2 will also set rc = 327. 

C Language 
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DosSetDateTime — 
Set Current Date and Time 


typedef struct _DATETIME { /* date */ 

UCHAR hours; /* current hour */ 

UCHAR minutes; /* current minute */ 

UCHAR seconds; /* current second *7 

UCHAR hundredths; /* current hundredths of a second */ 

UCHAR day; /* current day */ 

UCHAR month; /* current month */ 

USHORT year; /* current year */ 

SHORT timezone; /* minutes of time west of UTC */ 

UCHAR weekday; /* current day of week */ 

} DATETIME; 

#defi ne I NCLJ10S DATETIME 

USHORT rc = DosSetDateTime(DateTime) ; 

PDATETIME DateTime; /* Date/time structure */ 

USHORT rc; /* return code */ 

Assembler Language 

DATETIME struc 

datejiours db ? ; current hour 

datejni nutes db ? ; current minute 

date_second$ db ? ; current second 

datejiundredths db ? ; current hundredths of a second 
date_day db ? ; current day 

datejnonth db ? ; current month 

date^year dw ? ; current year 

date_timezone dw ? ; mi nutes of time west of UTC 

date_weekday db ? ; current day of week 

DATETIME ends 

EXTRN DosSetDateTime: FAR 
INCL.DOSDATETIME EQU 1 

PUSHG OTHER DateTime ; Date/time structure 

CALL DosSetDateTime 

Returns WORD 

Example 

The following example obtains and prints date and time information. It then changes the system date to 
5/10/1987 and prints the updated information. 

fdefine INCL_DOSDATETIME 

linclude <os2.h> 

main() 

{ 

DATETIME DateTime; /* Structure to hold date/time info. */ 

USHORT rc; 

rc - Do$GetDateTime(&DateTime); /* Address of d/t structure */ 
printf ("Today is %d-%d-%d; the time is %d:%d\n“, DateTime. month, 

DateTime. day, DateTime. year, DateTime. hours, DateTime. mi nutes); 

DateTime. day = 10; 

DateTime. month = 5; 

DateTime. year = 1987; 

printf ("The new date is %d-%d-%d; the time is %d:%d\n", DateTime. month, 

DateTime. day, DateTime. year, DateTime. hours, DateTime. mi nutes); 
rc c DosSetDateTimef&DateTime) ; /* Address of d/t structure */ 

printf("rc is %d\n", rc); 

} 
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Set File Handle State 


This call sets the state of the specified file. 


DosSetFHandState (FileHandle, FileHandleState) 


Parameters 

FileHandle (HFILE) - input 
File handle to be set. 

FileHandleState ( USHORT) - input 

Contents of the open mode word defined in a previous DosOpen or DosOpen2 call. 

Bit Description 

15 Zero Bit field. This bit must be set to zero. 

14 Write-Through flag: 

0 = Writes to the fiie may be run through the system buffer cache. 

1 = Writes to the file may go through the system buffer cache, but the data is written 
(actual file I/O completed) before a synchronous write call returns. This state of the file 
defines it as a synchronous file. For synchronous files, this is a mandatory bit in that the 
data must be written out to the medium for synchronous write operations. 

This bit is not inherited by child processes. 

13 Fail-Errors flag. Media I/O errors are handled as follows: 

0 = Reported through the system critical error handier. 

1 = Reported directly to the caller by way of a return code. 

Media I/O errors generated through an IOCTL category 8 function always get reported 
directly to the caller by way of a return code. The Fail-Errors function applies only to 
non-lOCTL handle-based type file I/O calls. 

This bit is not inherited by child processes. 

12 No-Cache/Cache flag. The file is opened as follows: 

0 = It is advisable for the disk driver to cache the data in I/O operations on this file. 

1 = I/O to the file need not be done through the disk driver cache. 

This bit is an advisory bit, and is used to advise FSDs and device drivers on whether it is 
worth caching the data or not. This bit, like the write-through bit, is a per-handle bit. 

This bit is not inherited by child processes. 

11-8 Reserved Bits. These bits are reserved and should be set to the values returned by 
DosQFHandState in these positions. 

7 Inheritance flag: 

0 = File handle is inherited by a spawned process resulting from a DosExecPgm call. 

1 = File handle is private to the current process. 

6-4 Zero Bit field. These bits must be set to zero. Any other values are invalid. 

3 Reserved Bit. This bit is reserved and should be set to the value returned by 

DosQFHandState for this position. 

2-0 Zero Bit fieid. These bits must be set to zero. Any other values are invalid. 

rc ( USHORT) - return 

Return code descriptions are: 
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Set File Handle State 

0 NO_ERROR 

6 ERRORJNVALIDJHANDLE 

87 ERROR_INVALID_PARAMETER 

Remarks 

OS/2 does not guarantee the order that sectors are written for multiple sector writes. If an application 
requires several sectors written in a specific order, the operator should issue them as separate synchro- 
nous write operations. Setting the write-through flag does not affect any previous writes. That data may 
remain in the buffers. When a critical error occurs that the application cannot handle, it may reset critical 
error handling to be performed by the system. This is done by calling DosSetFHandState to turn off the 
fail/errors bit and reissuing the I/O call. The expected critical error reoccurs and control is passed to the 
system critical error handler. The precise time that the effect of this function is visible at the application 
level is unpredictable when asynchronous I/O Is pending. 

The file handle state bits set by this function can be queried by DosQFHandState. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following 
restrictions apply to DosSetFHandState when coding for the DOS mode: 

• The validity of the file handle is not checked. 

• The Inheritance flag must be set equal to zero. (This flag is not supported in DOS 2.X.) 

• The Write-Through flag must be set equal to zero. 

• The Fail-Errors flag must be set equal to zero. 

Named Pipe Considerations 

DosSetFHandState allows setting of the inheritance (I) and Write-Through (W) bits. Setting W to 1 pre- 
vents write-behind operations on remote pipes. 

C Language 

♦define INCL_DOSFILEMGR 

USHORT rc = DosSetFHandState (FileHandle, FileHandl estate); 

HFILE FileHandle; /* File handle */ 

USHORT FileHandl estate; /* File handle state */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSetFHandState: FAR 
INCLJOSFILEKGR EQU 1 

PUSH WORD FileHandle ;File handle 

PUSH WORD FileHandl estate ;File handle state 

CALL DosSetFHandState 

Returns WORD 
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Set File Information 


FAPI 


This call sets attribute and extended attribute information for a file. 


DosSetFilelnfo (FileHandle, FilelnfoLevel, FiielnfoBuf, FilelnfoBufSize) 


Parameters 

FileHandle (HFILE) - input 
File handle. 

FilelnfoLevel ( USHORT) - input 

Level of file information being set. A value of 1 or 2 can be specified. The structures described in 
FiielnfoBuf indicate the information being set for each of these levels. 

FllelnfoBuf (PBYTE) - input 

Address of the storage area containing the structures for file information levels. 

Level 1 Information 

FiielnfoBuf contains the following structure, to which information is specified in the following 
format: 

filedate (FDATE) 

Structure containing the date of file creation. 

Bit Description 

15-9 Year, in binary, of file creation 
8-5 Month, in binary, of file creation 

4-0 Day, in binary, of file creation. 

filetime (FTIME) 

Structure containing the time of file creation. 

Bit Description 

15-11 Hours, in binary, of file creation 

10-5 Minutes, in binary, of file creation 

4-0 Seconds, in binary number of two-second increments, of file creation, 

fileaccessdate (FDATE) 

Structure containing the date of last access. See FDATE in filedate. 
fileaccesstime (FTIME) 

Structure containing the time of last access. See FTIME in filetime, 
writeaccessdate (FDATE) 

Structure containing the date of last write. See FDATE in filedate. 
writeaccesstime (FTIME) 

Structure containing the time of last write. See FTIME in filetime. 

fllesize (ULONG) 

File size. 

filealloc (ULONG) 

Allocated file size. 

fileattrib (USHORT) 

Attributes of the file, defined in DosSetFileMode. 

Level 2 Information • 

FiielnfoBuf contains an EAOP structure, which has the following format: 
fpGEALIst (PGEALIST) 

Address of GEAList. GEAList is a packed array of variable length “get EA M structures, each 
containing an EA name and the length of the name. 


2-326 Control Program Programming Reference 
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DosSetFilelnfo - 
Set File information 


fpFEAList (PFEAUST) 

Address of FEAList. FEAList is a packed array of variable length “full EA" structures, each 
containing an EA name and its corresponding value, as well as the lengths of the name and 
the value. 

oError (ULONG) 

Offset into structure where error has occurred. 

Level 2 sets a series of EA name/value pairs. On input, FilelnfoBuf is an EAOP structure above. 
fpGEAList is ignored. fpFEAList points to a data area where the relevant FEA list is to be found. 
oError is ignored. Following is the format of the FEAList structure: 

cbList (ULONG) 

Length of the FEA list, including the length itself, 
list (FEA) 

List of FEA structures. An FEA structure has the following format: 

Flags (BYTE) 

Bit indicator describing the characteristics of the EA being defined. 

Bit Description 

15 Critical EA. 

14-0 Reserved and must be set to zero. 

If bit 15 is set to 1, this indicates a critical EA. If bit 15 is 0, this means the EA is noncrit- 
ical; that is, the EA is not essential to the intended use by an application of the file with 
which it is associated. 

cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character. 
cbValue (USHORT) 

Length of EA value, which cannot exceed 64KB. 
szName (PSZ) 

Address of the ASCIIZ name of EA. 
aValue (PSZ) 

Address of the free-format value of EA. 

Note: The szName and aValue fields are not included as part of header or include files. 
Because of their variable lengths, these entries must be built manually. 

On output, fpGEAList is unchanged. fpFEAList is unchanged as is the area pointed to by 
fpFEAList. If an error occurred during the set, oError is the offset of the FEA where the error 
occurred. The API return code is the error code corresponding to the condition generating the 
error. If no error occurred, oError is undefined. 


FilelnfoBufSize ( USHORT) - input 

Length of FilelnfoBuf. 

rc ( USHORT) - 

return 

Return code descriptions are: 

0 

NO.ERROR 

1 

ERROR INVALID FUNCTION 

5 

ERROR_ACCESS_DENIED 

6 

ERRORJNVALI D_H AN DLE 

87 

ERROR_INVALID_PARAMETER 

122 

ERRORJNSUFFICIENT_BUFFER 

124 

ERROR_INVALID_LEVEL 

130 

ERROR_DIRECT_ACCESS_HANDLE 

254 

ERROR_INVALID_EA_NAME 

255 

ERROR_EA_LIST_INCONSISTENT 
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Set File Information 


FAPI 


Remarks 

DosSetFilelnfo is successful only when the file is opened for write access, with a deny-both sharing mode 
specified for access to the file by other processes. If the file is already opened with conflicting sharing 
rights, the call to DosOpen or DosOpen2 will fail. 

A 0 value in the date and time components of a field does not change the field. For example, if both ‘Mast 
write date" and ‘Mast write time" are specified as 0 in the Level 1 information structure, then both attri- 
butes of the file are left unchanged. If either “last write date" or “last write time" are specified as non- 
zero, both attributes of the file are set to the new values. 

The FAT file system supports modification of only the dates and times of the last write. Creation and last 
access dates and times are not affected. 

The last modification date and time will get changed if the extended attributes are modified. 

Family API Considerations 

It is not possible to create a label with leading blank characters in DOS mode, because of restrictions on 
the previous Interrupt 21 h function call (create an FCB type file), which must be used by FAPI. 

C Language 

typedef struct _FDATE { /* fdate */ 

unsigned day : 5; /* binary day for directory entry */ 

unsigned month : 4; /* binary month for directory entry */ 

unsigned year : 7; /* binary year for directory entry */ 

} FDATE; 

typedef struct JTIME { /* ftime */ 

unsigned twosecs : 5; /* binary number of two-second increments */ 

unsigned minutes : 6; /* binary number of minutes */ 

unsigned hours ; 5; /* binary number of hours */ 

} FTIME; 

typedef struct _FILESTATUS { /* fsts */ 

FDATE fdateCreation; /* date of file creation */ 

FTIME ftimeCreation; /* time of file creation */ 

FDATE fdateLastAccess; /* date of last access */ 

FTIME ftimeLastAccess; /* time of last access */ 

FDATE fdateLastWrite; /* date of last write */ 

FTIME ftimeLastWrite; /* time of last write */ 

ULONG cbFile; /* file size (end of data) */ 

ULONG cbFileAlloc; /* file allocated size */ 

USHORT attrFile; /* attributes of the file */ 

} FILESTATUS; 
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typedef struct _GEA { /* gea */ 

BYTE cbName; /* name length not including NULL */ 

CHAR szName[l]; /* attribute name */ 

} SEA; 

typedef struct JSEALIST { /* geal */ 

ULONG cbList; /* total bytes of structure including full list */ 

GEA 1 ist [1] ; /* variable length GEA structures */ 

} GEALIST; 

typedef struct _FEA { /* fea */ 

BYTE fEA; /* flags */ 

BYTE cbName; /* name length not including NULL */ 

USHORT cbValue; /* value length */ 

} FEA; 

typedef struct _FEALIST { /* feal */ 

ULONG cbList; /* total bytes of structure including full list */ 

FEA list [1] ; /* variable length FEA structures */ 

} FEAL I ST; 

typedef struct _EAQP { /* eaop */ 

PGEALIST fpGEAList; fie general EA list */ 

PFEALIST fpFEAList; lie full EA list ief 

ULONG oError; 

} EAOP; 

fdefine INCL_D0SF1LEMGR 

USHORT rc = DosSetFileInfo(FileHandle. FilelnfoLevel , FilelnfoBuf, 

FilelnfoBufSi ze) ; 


HFILE 

FileHandle; 

/ie File handle ie / 

USHORT 

FilelnfoLevel ; 

/ie File info data required ★/ 

PBYTE 

FilelnfoBuf; 

/ie File info buffer ief 

USHORT 

FilelnfoBufSize; 

fie File info buffer size */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 
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DosSetFilelnfo - 
Set File Information 


FAPI 


FDATE struc 
fdate_fs dw ? 

FDATE ends 
FTIME struc 
ftime_fs dw ? 

FTIME ends 
FILESTATUS struc 

f sts_f dat eCreat i on dw (size FDATE) /2 dup (?) ;date of file creation 

f sts _fti meCreati on dw (size FTIME)/2 dup (?) ;time of file creation 

fsts_fdateLastAccess dw (size FDATE) /2 dup (?) jdate of last access 

fsts_ftimeLastAccess dw (size FTIMEJ/2 dup (?) ;time of last access 

f sts_f dateLastWri te dw (size FDATE) /2 dup (?) ;date of last write 

fsts_ftimeLastWrite dw (size FTIME)/2 dup (?) ;time of last write 

fstsjrbFile dd ? ;file size (end of data) 

fsts_cbFileAlloc dd ? ;file allocated size 

fsts_attrFile dw ? ; attributes of the file 

FILESTATUS ends 
6EA struc 

gea_cbName db ? ;name length not including NULL 

gea_szName db 1 dup (?) jattribute name 

GEA ends 

GEALIST struc 

geal_cbList dd ? ; total bytes of structure including full list 

gealjist db size GEA * 1 dup (?) ; variable length GEA structures 

GEALIST ends 

FEA struc 

fea_fEA db ? ;flags 

fea_cbName db ? ;name length not including NULL 
fea_cbValue dw ? ; value length 

FEA ends 

FEALIST struc 

feal_cbList dd ? ; total bytes of structure including full list 

feal_l ist db size FEA * 1 dup (?) ; variable length FEA structures 

FEALIST ends 

EAOP struc 

eaop_f pGEALi st dd ? ;general EA list 
eaop_f pFEALi st dd ? ;full EA list 

eaop_oError dd ? ; 

EAOP ends 

EXTRN DosSetFilelnfo: FAR 
INCLJ)OSFILEMGR EQU 1 

PUSH WORD FileHandle ; Fi 1 e handle 

PUSH WORD Fi lelnfoLevel ; Fi 1 e info data required 

PUSHg OTHER FilelnfcBuf ;File info buffer 

PUSH WORD Fi lelnfoBufSize ;File info buffer size 

CALL DosSetFilelnfo 

Returns WORD 
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FAPI 


DosSetFileMode - 
Set File Mode 


This call changes the mode (attribute) of the specified file. 


DosSetFileMode (FlleName, NewAttrlbute, Reserved) 


Parameters 

FlleName (PSZ) - input 

Address of the file path name. 

DosQSysInfo is called by an application during initialization to determine the maximum path length 
allowed by OS/2. 

NewAttrlbute (USHORT) - input 

File’s new attribute. File attributes are defined as follows: 

Bit Description 

15-6 Reserved and must be zero. 

5 File archive 

4 Subdirectory 

3 Volume label 

2 System file (excluded from normal directory searches) 

1 Hidden file 

0 Read only file 

These bits may be set Individually or in combination. For example, an attribute value of 0021 H (bits 5 
and 0 set to 1) indicates a read-only file that should be archived. 

Reserved ( ULONG ) - input 

Reserved must be set to zero. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

2 ERROR_FILE_NOT_FOUND 

3 ERROR_PATH_NOT_FOUND 

5 E R RO R_ACC ESS_DEN I E D 

26 ERROR_NOT_DOSJDISK 

32 ERROR_SHARING_VIOLATION 

36 error~sharing_buffer_exceeded 

87 ERRORJNVALID_PARAMETER 

108 ERROR_DRIVEJ_OCKED 

206 ERROR_FILENAME_EXCED_RANGE 

Remarks 

Attributes for Volume Label (0008H) and Subdirectory (0010H) cannot be changed using DosSetFileMode. 

If these attributes are specified, ERRORJNVALID_PARAMETER is returned. 

DosQFileMode is used to query the current settings for file attributes. Calling DosQFSInfo obtains volume 
label information. 

Attributes of root directories cannot be changed using DosSetFileMode. If these attributes are specified, 

E R RO R_ACCESS_DE N I E D is returned. 
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DosSetFileMode 
Set File Mode 


FAPI 


C Language 

#define INCL_DOSFILEMGR 

USHORT rc ° DosSetFileMode (FileName, NewAttribute, Reserved); 

PSZ FileName; /* File path name string */ 

USHORT NewAttribute; /* New attribute of file */ 

ULONG 0; /* Reserved (must be zero) */ 

USHORT rc; /* return code */ 


Assembler Language 

EXTRN DosSetFileMode: FAR 
INCL_DOSFILEKGR EQU 1 

PUSH® ASCI IZ FileName ; Fi 1 e path name string 
PUSH WORD NewAttribute ;New attribute of file 
PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosSetFileMode 

Returns WORD 
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fapi DosSetFSInfo - 

Set File System Information 


This call sets information for a file system device. 


DosSetFSInfo (DriveNumber, FSInfoLevel, FSInfoBuf, FSInfoBufSize) 


Parameters 

DriveNumber (USHORT) - input 

Logical drive number, for example, 0 = default and 1 = A, and the FSD for the media currently in that 
drive. A value of 'OxFFFF' notes that FSInfoBuf contains the ASCIIZ path name of the FSD. 

FSInfoLevel (USHORT) - input 

Level of file information to be set. A value of 2 is the only valid value for FSInfoLevel. 

FSInfoBuf (PBYTE) - input 

Address of the storage area where the system gets the new file system information. 

Level 2 Information 

Level 2 information is specified in the following format: 

Byte Description 

1 Length of Volume Label (null not included) 

2 - N Volume Label ASCIIZ string. 

FSInfoBufSize (USHORT) - input 
Length of FSInfoBuf. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

15 ERROR JNVALI DJDRIVE 

82 ERR0RJ3ANN0T_ MAKE 

122 ERROR JNSUFFICIENT_BUFFER 

123 ERRORJNVALID_NAME 

124 ERROR_INVALID_LEVEL 

154 ERROR_LABEL_TOOJ-ONG 

Remarks 

Trailing blanks supplied at volume label definition time are not returned by DosQFSInfo. 

File system information can be set only if the volume is opened in a mode that allows write-access. 

C Language 

#define INCL_DOSFILEMGR 

USHORT rc = Dos$etF$Info(Dri veNumber, FSInfoLevel, FSInfoBuf, FSInfoBufSize); 

USHORT DriveNumber; /* Drive number */ 

USHORT FSInfoLevel; /* File system data type */ 

PBYTE FSInfoBuf; /* File system info buffer */ 

USHORT FSInfoBufSize; /* File system info buffer size */ 

USHORT rc; /* return code */ 
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DosSetFSInfo - 

Set File System Information 


FAPI 


Assembler Language 

EXTRN DosSetFSInfo: FAR 
INCL_DOSFILEMGR EQU 1 

PUSH WORD DriveNumber ; Drive number 

PUSH WORD FSInfoLevel ;Fi 1 e system data type 

PUSH® OTHER FSInfoBuf ;File system info buffer 

PUSH WORD FSInfoBufSi ze ;File system info buffer size 

CALL DosSetFSInfo 

Returns WORD 
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DosSetMaxFH - 
Set Maximum File Handles 


This call defines the maximum number of file handles for the current process. 


DosSetMaxFH (NumberHandles) 


Parameters 

NumberHandles ( USHORT) - input 

Total number of file handles to be provided. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

8 ERROR_NOT_ENOUGH_M EMORY 

87 ERRORJNVALID_PARAMETER 

Remarks 

OS/2 initially allots 20 file handles to a process, which is the recommended amount for an application. 
However, if the system limit has not been reached, this amount can be increased with DosSetMaxFH. 
When this call is made, all open file handles are preserved. 

C Language 

Idefine INCL_DOSFILEMGR 

USHORT rc - DosSetMaxFH(NuniberHandles) ; 

USHORT NumberHandles; /* Number of file handles */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSetMaxFH: FAR 
INCLJOSFILEMGR EQU 1 

PUSH WORD NumberHandles ; Number of file handles 
CALL DosSetMaxFH 

Returns WORD 
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DosSetNmPHandState - 
Set Named Pipe Handle State 


This call sets the read and blocking modes of a named pipe. 


DosSetNmPHandState (Handle, PipeHandleState) 


Parameters 

Handle (HPIPE) - input 

Handle of the named pipe returned by DosMakeNmPipe or DosOpen. 

PipeHandleState ( USHORT) - input 

Named pipe handle state, consists of the following bit fields: 

Bit Description 

15 Blocking flag: 

0 = Reads /Writes block if no data available. 

1 = Reads/Writes return immediately if no data available. 

Reads normally block until at least partial data can be returned. Writes by default block 
until all bytes requested have been written. Non-blocking mode (B = 1) changes this 
behavior as follows: 

DosRead Returns BytesRead = 0 if no data is available. 

DosWrite Returns BytesWritten = 0 if there is not enough buffer space available in the 

pipe. Otherwise, the entire data area is transferred. 

14-10 Reserved and must be set to zero. 

9-8 Read Mode flag: 

00 = Read pipe as byte stream. 

01 = Read pipe as a message stream. 

7-0 Reserved and must be set to zero. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

87 ERROR_INVALID_PARAMETER 

230 ERROR__BAD_PIPE 

231 ERROR_PIPE_BUSY 

233 ERROR_PIPElNOT_CONNECTED 

Remarks 

The read mode and blocking/non-blocking mode of a named pipe can be changed. The pipe mode can 
not be changed to non-blocking when another thread is blocked on an I/O to the same end of the pipe. 

C Language 

#defi ne INCLJ)OSNMPIPE$ 

USHORT rc = DosSetNmPHandState (Handle. PipeHandleState); 

HPIPE Handle; /* Pipe handle */ 

USHORT PipeHandleState; /* Pipe handle state */ 

USHORT rc; /* return code */ 


2-336 Control Program Programming Reference 







DosSetNmPHandState — 
Set Named Pipe Handle State 


Assembler Language 

EXTRN DosSetNmPHandState : FAR 
INCLJ50SNMPIPES EQU 1 

PUSH WORD Handle ;Pipe handle 

PUSH WORD Pi peHandl estate ;Pipe handle state 

CALL DosSetNmPHandState 

Returns WORD 
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DosSetNmPipeSem - 
Set Named Pipe Semaphore 


This call attaches a system semaphore to a local named pipe. 


DosSetNmPipeSem (Handle, SemHandle, KeyHandle) 


Parameters 

Handle ( HPIPE ) - input 

Handle of the named pipe returned by DosMakeNmPipe or DosOpen. 

SemHandle (HSEM) - input 

A system semaphore handle that is cleared when the pipe (identified by Handle) has read data or 
write space available. 

KeyHandle ( USHORT) - input 

An arbitrary value that is used to associate named pipe actions with result codes in 
DosQN m Pi peSemState. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

87 ERRORJNVALID_PARAMETER 

120 ERRORJNVALID_FUNCTION 

187 ERROR_SEM_NOT_FOUND 

230 ERROR_BAD_PIPE~ 

233 ERROR_PIPEJSlOT_CONNECTED 

Remarks 

This call is intended for use only with local named pipes. If an attempt is made to attach a semaphore to 
a remote named pipe, ERROR_INVALID_FUNCTION is returned. 

DosSetNmPipeSem supports serving applications that need to handle a large number of incoming pipes. 
By using semaphores, the application avoids such resource-consuming methods as dedicating a thread 
for each incoming pipe, or polling each pipe with non-blocking I/O. Instead, the application issues a 
DosSemWait or a DosMuxSemWait and waits for notification that I/O can be performed. 

The system semaphore indicated by SemHandle is attached to the named pipe indicated by Handle. Up 
to two semaphores may be attached to a pipe, one for the serving side and one for the client side. If a 
semaphore is already attached to a side of the pipe, the semaphore is overridden. 

The arbitrary value assigned to KeyHandle as input for DosSetNmPipeSem is used by 
DosQNmPipeSemState as output. This enables the application to distinguish events specific to a partic- 
ular pipe when several pipes are attached to the same semaphore. DosQNmPipeSemState can be used 
to provide additional information about the I/O that can be performed on the set of pipes. 

C Language 

^define INCL.DOSNMPIPES 

USHORT rc 3 DosSetNmPipeSem (Handle, SemHandle, KeyHandle); 


HPIPE 

Handle; 

/* Pipe handle */ 

HSEM 

SemHandle; 

/* Semaphore handle */ 

USHORT 

KeyHandle; 

/* Key value */ 

USHORT 

rc; 

/* return code */ 
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DosSetNmPipeSem — 
Set Named Pipe Semaphore 


Assembler Language 

EXTRN DosSetNmPipeSem: FAR 
INCL_DOSNMPIPES EQU 1 


PUSH 

WORD 

Handle 

PUSH 

DWORD 

SemHandl e 

PUSH 

WORD 

KeyHandl e 

CALL 

DosSetNmPipeSem 


;Pipe handle 
; Semaphore handle 
;Key value 


Returns WORD 
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DosSetPathlnfo - 

Set Information for a File or Directory 


This call sets attribute and extended attribute information for a file or subdirectory. 


DosSetPathlnfo (PathName, PathlnfoLevel, PathlnfoBuf, PathlnfoBufSIze, PathlnfoFlags, Reserved) 


Parameters 

PathName ( PSZ ) - input 

Address of the ASCIIZ full path name of the file or subdirectory. Global file name characters are not 
permitted. 

DosQSysInfo is called by an application during initialization to determine the maximum path length 
allowed by OS/2. 

PathlnfoLevel (USHORT) - input 

Level of file object information being defined. A value of 1 or 2 can be specified. The structures 
described in PathlnfoBuf indicate the information being set for each of these levels. 

PathlnfoBuf (PBYTE) - input 

Address of the storage area containing the file information being set. 

Level 1 Information 

PathlnfoBuf contains the following structure, to which information is specified in the following 
format: 

filedate (FDATE) 

Structure containing the date of creation. 

Bit Description 

15-9 Year, in binary, of creation 

8-5 Month, in binary, of creation 

4-0 Day, in binary, of creation. 

filetime (FTIME) 

Structure containing the time of creation. 

Bit Description 

15 — 11 Hours, in binary, of creation 

10-5 Minutes, in binary, of creation 

4-0 Seconds, in binary number of two-second increments, of creation, 

fileaccessdate (FDATE) 

Structure containing the date of last access. See FDATE in filedate. 
fileaccesstime (FTIME) 

Structure containing the time of last access. See FTIME in filetime, 
wrlteaccessdate (FDATE) 

Structure containing the date of last write. See FDATE in filedate. 
writeaccesstime (FTIME) 

Structure containing the time of last write. See FTIME in filetime. 

Level 2 Information 

PathlnfoBuf contains an EAOP structure, which has the following format: 
fpGEALIst (PGEALIST) 

Address of GEAList. GEAList is a packed array of variable length “get EA" structures, each 
containing an EA name and the length of the name. 

fpFEALIst (PFEALIST) 

Address of FEAList. FEAList is a packed array of variable length "full EA" structures, each 
containing an EA name and its corresponding value, as well as the lengths of the name and 
the value. 
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DosSetPathlnfo - 

Set Information for a File or Directory 


oError (ULONG) 

Offset into structure where error has occurred. 

Level 2 sets a series of EA name/value pairs. On input, FilelnfoBuf is an EAOP structure above. 
fpGEAList is ignored. fpFEAList points to a data area where the relevant FEA list is to be found. 
oError is ignored. Following is the format of the FEAList structure: 

cbLIst (ULONG) 

Length of the FEA list, including the length itself, 
list (FEA) 

List of FEA structures. An FEA structure has the following format: 

Flags (BYTE) 

Bit indicator describing the characteristics of the EA being defined. 

Bit Description 

15 Critical EA. 

14 — 0 Reserved and must be set to zero. 

If bit 15 is set to 1, this indicates a critical EA. If bit 15 is 0, this means the EA is noncrit- 
ical; that is, the EA is not essential to the intended use by an application of the file with 
which it is associated. 

cbName (BYTE) 

Length of EA ASCIIZ name, which does not include the null character. 
cbValue (USHORT) 

Length of EA value, which cannot exceed 64KB. 
szName (PSZ) 

Address of the ASCIIZ name of EA. 
aValue (PSZ) 

Address of the free-format value of EA. 

Note: The szName and aValue fields are not included as part of header or include files. 
Because of their variable lengths, these entries must be built manually. 

On output, fpGEAList is unchanged. fpFEAList is unchanged as is the area pointed to by 
fpFEAList. If an error occurred during the set, oError is the offset of the FEA where the error 
occurred. The API return code is the error code corresponding to the condition generating the 
error. If no error occurred, oError is undefined. 

PathlnfoBufSIze (USHORT) - input 
Length of PathlnfoBuf. 

PathlnfoFlags (USHORT) - input 

PathlnfoFlags contain information on how the set operation is performed. Only one bit is defined. If 
PathlnfoFlags = 0010H, then the information being set must be written out to disk before returning to 
the application. This guarantees that the EAs have been written to disk. All other bits are reserved 
and must be zero. 

Reserved (ULONG) - input 

Reserved, must be set to zero. 

rc (USHORT) - return 


Return code 

t descriptions are: 

0 

NO_ERROR 

32 

ERROR_SHARING_VIOLATION 

87 

ER ROR JN VALI D_P AR AM ETER 

124 

ERRORJNVALIDJ.EVEL 

206 

ERROR_FILENAME_EXCED_RANGE 

122 

ERRORJNSUFFICIENT_BUFFER 

254 

E R ROR J NVALI D_E A_N AM E 

255 

ERROR_EAJJSTJNCONSISTENT 
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DosSetPathlnfo - 

Set Information for a File or Directory 


FAPI 


Remarks 

To set any level of file information for a file or subdirectory with DosSetPathlnfo, a process must have 
exclusive write access to the closed file object. Thus, if the file object is already accessed by another 
process, a call to DosSetPathlnfo fails. 

A zero (0) value in both the date and time components of a field cause that field to be left unchanged. For 
example, if both “Last write date’’ and “Last write time’ 1 are specified as zero in the Level 0001H informa- 
tion structure, then both attributes of the file are left unchanged. If either "Last write date” or "Last write 
time” are specified as non-zero, then both attributes of the file are set to the new values. 

The write-through bit in Pathlnfo Flags should be used only in cases where it is necessary, for data integ- 
rity purposes, to write the EAs out to disk immediately, instead of caching them and writing them out 
later. Setting the write-through bit all the time may degrade the performance. 

The last modification date and time will get changed if the extended attributes are modified. 

C Language 

typedef struct _GEA { /* gea */ 

BYTE cbName; /* name length not including NULL */ 

CHAR szName[l]; /* attribute name */ 

} GEA; 

typedef struct _GEALIST { /* geal */ 

ULONG cbList; /* total bytes of structure including full list */ 

GEA list [1] ; /* variable length GEA structures */ 

} GEALIST; 

typedef struct _FEA { /* fea */ 

BYTE fEA; /* flags */ 

BYTE cbName; /* name length not including NULL */ 

USHORT cbValue; /* value length */ 

} FEA; 

typedef struct REALIST { /* feal */ 

ULONG cbList; /* total bytes of structure including full list */ 

FEA list [1] ; /* variable length FEA structures */ 

} FEALIST; 

typedef struct _EA0P { /* eaop */ 

PGEALIST fpGEAList; /* general EA list */ 

PFEALIST fpFEAList; /* full EA list */ 

ULONG oError; 

} EAOP; 

#define INCL.DOSFILEMGR 

USHORT rc = DosSetPathInfo(PathName, PathlnfoLevel f PathlnfoBuf, Path InfoBuf Size, PathlnfoFlags, 0); 


PSZ 

PathName; 

/* File or directory path name string */ 

USHORT 

PathlnfoLevel ; 

/* Info data type */ 

PBYTE 

PathlnfoBuf; 

/* Info buffer */ 

USHORT 

Path InfoBuf Size; 

/* Info buffer size */ 

USHORT 

PathlnfoFlags; 

/* Path info flags */ 

ULONG 

0; 

/* Reserved (must be zero) */ 

USHORT 

rc; 

/* return code */ 
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fapi DosSetPathlnfo - 

Set Information for a File or Directory 

Assembler Language 

GEA struc 

gea_cbName db ? ;name length not including NULL 

gea_szName db 1 dup (?) attribute name 

GEA ends 

GEALIST struc 

geal_cbList dd ? ; total bytes of structure including full list 

gealjist db size GEA * 1 dup (?) ; variable length GEA structures 

GEALIST ends 

FEA struc 

fea_fEA db ? jflags 

feajrbName db ? ;name length not including NULL 

fea_cbValue dw ? ; value length 

FEA ends 

FEALIST struc 

feal_cbList dd ? ; total bytes of structure including full list 

fealjist db size FEA * 1 dup (?) ; variable length FEA structures 

FEALIST ends 

EAOP struc 

eaop fpGEAList dd ? ; general EA list 

eaop”f pFEALi st dd ? -.full EA list 

eaop_oError dd ? ; 

EAOP ends 

EXTRN DosSetPathlnfo: FAR 
INCL.DOSFILEMGR EQU 1 

PUSH? ASCI I Z PathName ; Fi 1 e or directory path name string 

PUSH WORD PathlnfoLevel ;Info data type 

PUSH? OTHER PathlnfoBuf ;Info buffer 

PUSH WORD PathlnfoBuf Size ;Info buffer size 

PUSH WORD Flags ;Path info flags 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosSetPathlnfo 

Returns WORD 
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DosSetProcCp - 
Set Process Code Page 


This call allows a process to set its code page. 


DosSetProcCp (CodePage, Reserved) 


Parameters 

CodePage ( USHORT) - input 

Code page identifier word that has one of the following values: 

Value Definition 
437 IBM PC US 437 code page 

850 Multilingual code page 

860 Portuguese code page 

863 Canadian-French code page 

865 Nordic code page. 

Reserved ( USHORT) - input 

Reserved must be set to zero. 

rc ( USHORT) - return 

Return code description is: 

0 NO_ERROR 

472 ERROR_INVALID_CODEPAGE 

Remarks 

DosSetProcCp sets the process code page of the calling process. The code page of a process is used in 
the following ways. First, the printer code page is set to the process code page through the file system 
and printer spooler when the process makes an open printer request. Calling DosSetProcCp does not 
affect the code page of a printer opened prior to the call and does not affect the code page of a printer 
opened by another process. Second, country dependent information, by default, is retrieved encoded in 
the code page of the calling process. And third, a newly created process inherits its process code page 
from its parent process. DosSetProcCp does not affect the display or keyboard code page. Also see 
DosSetCp. 


C Language 


Idefine 

INCL_00SNLS 


USHORT 

rc = DosSetProcCp (CodePage, Reserved); 

USHORT 

CodePage; 

/* Code page identifier */ 

USHORT 

0; 

/* Reserved, set to zero */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosSetProcCp: FAR 
INCL_D0SNLS EQU 1 

PUSH WORD CodePage ;Code page identifier 

PUSH WORD 0 Reserved (must be zero) 

CALL DosSetProcCp 

Returns WORD 
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DosSetPrty - 
Set Process Priority 


This call allows a process to change the priority of all the threads of any process; or all the threads of the 
current process or a child process, as well as any descendants; or a single thread within the current 
process. When a process changes the priority of threads in other processes, only default priorities are 
changed. 


DosSetPrty (Scope, PrlorityClass, PriorityDelta, ID) 


Parameters 

Scope ( USHORT) - input 

The extent of the priority change. 

Value Definition 

0 All the threads of any process. 

1 All the threads of a process and any descendants. The indicated process must be the 
current process or a process created by the current process. Detached processes may 
not be specified. The indicated process may possibly have terminated. 

2 A single thread of the current process. 

PrlorityClass (USHORT) - input 

Priority class of a process. The values and descriptions are: 

Value Definition 

0 No change, leave as is 

1 Idle-time 

2 Regular 

3 Time-critical. 

4 Fixed-high. 

PriorityDelta ( SHORT) - input 

Delta priority to apply to the process's current base priority level. This value must range from —31 to 
+31. 

ID (USHORT) - input 

A process ID (scope = 0 or 1) or a thread ID (scope = 2). If this operand is equal to zero, the current 
process or thread is assumed. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

303 ERRORJNVALID_PROCID 

304 ERRORJNVALID.PDELTA 

305 ER ROR_NOT_DESCEN D ANT 

307 E R ROR J N V ALI D_PCL ASS 

308 ERROR_INVALID_SCOPE 

309 ERRORJNVALIDJTHREADID 

Remarks 

The OS/2 scheduler has a concept of priority classes and levels. DosSetPrty allows threads to move 
between classes in response to changes in their execution environments. Within each class, a thread's 
priority level can vary because of a DosSetPrty request or action taken by the system. System-initiated 
priority variation is performed as a combination of a specific thread's actions and the overall system 
activity. 


A time-critical thread has the highest priority class and executes before any fixed-high, regular, or idle- 
time threads. A fixed-high thread has a priority class that is lower than time-critical but executes before 
any regular or idle-time threads. 
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DosSetPrty - 
Set Process Priority 


Time-critical threads have static priorities that are not varied by OS/2. Threads are scheduled in priority 
order, with round-robin scheduling of threads of equal priority. 

For each of the four priority classes, there are 32 distinct priority levels, 0 to +31. Whenever DosSetPrty 
is issued with a class specification, but no value is specified for PriorityDelta, the base priority level 
defaults to zero. 


The priority level of a process consists of a computed priority value that is based upon the display status 
(foreground or background) of the process, its recent I/O and processor time-usage history, and other 
factors. The signed value specified in PriorityDelta is added to the computed priority to produce the 
actual priority used by the scheduler. The result is restricted to the valid range, based upon the current 
priority class. 

Specifying a higher priority delta allows a thread to obtain better processor scheduling than it normally 
would. A lower priority delta gives the thread less processor resource than it normally receives. 

When used with PriorityClass to change to a different class, the delta value applies to the base priority. A 
new base level of 0 is assigned the target thread and any PriorityDelta specified is relative to zero. 

A process can change the priority of any thread within its current process. However, when a process 
changes the priority of threads in another process, only those with default priorities are changed. The 
priority of any thread in another process that has explicitly changed its priority from the default with 
DosSetPrty is not changed. 

The initial thread of execution for an application is given a regular class priority that varies by the 
system. A thread started with DosCreateT hr;ead Inherits the priority of the thread in the process that 
creates it. A child process started by a DosExecPgm call inherits the priority of the thread in the parent 
process that creates it. 


C Language 

f define INCL_DOSPROCESS 


USHORT rc » DosSetPrty (Scope, PriorityClass, PriorityDelta, ID); 


USHORT 

USHORT 

SHORT 

USHORT 


Scope; 

PriorityClass; 

PriorityDelta; 

ID; 


/* Indicate scope of change */ 
/* Priority class to set */ 

/* Priority delta to apply */ 
/* Process or thread ID */ 


USHORT rc; 


/* return code */ 


Assembler Language 


EXTRN DosSetPrty: FAR 
INCL_DOSPROCESS EQU 1 


PUSH 

PUSH 

PUSH 

PUSH 

CALL 


WORD Scope 

WORD PriorityClass 

WORD PriorityDelta 

WORD ID 

DosSetPrty 


; Indicate scope of change 
; Priority class to set 
; Priority delta to apply 
; Process or thread ID 


Returns WORD 


Example 

The following example illustrates how to obtain the priority of a thread and how to change the priority. 
The main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that 
prints a line and then sleeps, relinquishing its time slice to the main thread. After one or two iterations 
by Thread2, the main thread obtains Thread2's priority information and prints it. It then raises Thread2's 
priority to fixed-high, and increments the level by ten. Since Thread2 is now at a high priority, it imme- 
diately finishes its remaining iterations before relinquishing control on a long sleep; at this point, the 
main thread re-examines Thread2 / s priority and reports its new priority level. In this example, it is 
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helpful to understand how the DosSleep calls are used either to relinquish control of the processor, or to 
keep a thread alive (see DosTimerAsync or DosTimerStart for alternatives to DosSleep). 

#define INCLJ)0$PR0CESS 
linclude <os2.h> 


#def i ne 

PRTYC FIXEDHIGH 

4 

/* Priority class: fixed-high */ 

Idefine 

PRTY DELTA 

10 

fie Priority delta: increase by 10 lef 

Idefine 

SEGSIZE 

4000 

fie Number of bytes requested in segment lef 

Idefine 

ALLOCFLAGS 

0 

fie Segment allocation flags - no sharing */ 

#def i ne 

SLEEPSHORT 

0L 

fie Sleep interval - 5 milliseconds lef 

Idefine 

SLEEPLONG 

20L 

fie Sleep interval - 75 milliseconds lef 

Idef i ne 

RETURN CODE 

0 

fie Return code for DosExi t() lef 


VOID API ENTRY Thread2() 

{ 

USHDRT i ; 

/* Loop with four iterations */ 
for(i=l; i<5; i++) 

{ 

printf("In Thread2, i is now %d\n H t i); 

/** Sleep to relinquish time slice to main thread **/ 

DosSleep (SLEEPSHORT) ; /* Sleep interval */ 

} 

DosExi t(EXIT_THREAD, /* Action code - end a thread */ 

RETURN CODE) ; fie Return code */ 

} 
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main() 


USHORT 

Priority; 

/* Thread priority k/ 

USHORT 

Class; 

/k Priority class k/ 

USHORT 

Level ; 

/k Priority level k/ 

SEL 

ThreadStackSel ; 

/k Segment selector for thread stack k/ 

PBYTE 

StackEnd; 

/k Ptr. to end of thread stack */ 

USHORT 

rc; 



/* Allocate segment for thread stack; this is better than just */ 

/* declaring an array of bytes to use as a stack. Make pointer eos. */ 
rc = DosA11ocSeg(SEGSIZE, /* Number of bytes requested */ 

aThreadStackSel , /* Segment selector (returned) */ 

ALLOCFLAGS) ; /* Allocation flags */ 

StackEnd = MAKEP(ThreadStackSel , SEGSIZE-1); 


/* Start Thread2 */ 

i f ( ! (DosCreat eThread ( ( PFNTHREAD) Thread2, 
aThreadID, 
StackEnd))) 
printf("Thread2 created. \n") ; 


/* Thread address */ 

/* Thread ID (returned) */ 
/* End of thread stack */ 


/** Sleep to allow Thread2 to execute **/ 

if (! (DosSI eep (SLEEPLONG) ) ) /* Sleep interval */ 

print f ("Slept a little to let Thread2 execute, \n'*); 


/** Obtain Thread2's priority information and report it **/ 


if (! ( rc=DosGet Pr ty ( PRTYSJTHRE AD , 
apriority, 
ThreadID))) 

{ 

/* Extract priority class and level 
Class = HI BYTE (Priority) ; 

Level ** LOBYTE (Priority) ; 
printf("Thread2: ID is %d. Priority 
ThreadID, Class, Level); 

} 

I irk Raise Thread2*s priority kk/ 
i f ( ! (rc=DosSetPrty(PRTYS_THREAD, 

PRTYC.FIXEDHIGH, 

PRTY^DELTA, 

ThreadID))) 


/k Scope - single thread k/ 
/k Address to put priority k/ 
/k ID - thread ID k/ 

information k/ 


Class is %d and Level is %d\n". 


/* Scope - single thread k/ 

/k Prty class - fixed-high k/ 

/k Prty delta - increase by 10 kf 
/k ID - thread ID k/ 


fk Obtain Thread2' new priority information and report it kf 
rc=DosGetPrty(PRTYS_THREAD, /k Scope - single thread k/ 

apriority, /* Address to put priority k/ 

ThreadID); /* ID - thread ID k/ 


/k Extract priority class and level information k/ 

Class = HI BYTE (Priority) ; 

Level = LOBYTE (Priority); 

printf ( M Thread2; ID is %d. New Priority Class is %d and Level is %d\n", 
ThreadID, Class, Level); 

> 

} 


2-348 Control Program Programming Reference 



DosSetSession - 
Set Session Status 


This call sets the status of a child session. 


DosSetSession (SessID, StatusData) 


Parameters 

SessID ( USHORT) - input 

ID of the target session. The value specified for SessID must have been returned on a prior call to 
DosStartSession. 

StatusData ( PSTATUSDATA ) - input 

Address of the session status data structure: 

length (USHORT) 

Length of structure, including length. 

6 Only valid value, 

selectlnd (USHORT) 

Specifies whether the target session is flagged as selectable or non-selectable: The operator 
can continue to select a non-selectable (bonded) windowed session by pressing a mouse button 
within a visible part of the window. 

Value Definition 

0 Leave current setting unchanged. 

1 Selectable. 

2 Non-selectable. 

bondlnd (USHORT) 

Specifies which session to bring to the foreground the next time the parent session is selected. 
The operator may continue to select a non-selectable (bonded) windowed session by pressing a 
mouse button within a visible part of the window. 

Value Definition 

0 Leave current setting unchanged. 

1 Establish a bond between parent session and child session. The child session is 
brought to the foreground the next time the parent session is selected, or when the 
child session itself is selected. 

2 Bring either the parent session to the foreground the next time the parent session is 
selected, or the child session if the child session is selected. Any bond previously 
established with a child session is broken. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

369 ERROR_SMGJNVALID - SESSIONJD 

418 ERROR_SMG_INVALID_CALL 

452 ERROR_SMG_SESSION_NOT_PARENT 

455 ERROR_SMGJNVALID_BOND_OPTION 

456 E R RO R_S M G J N V ALI D_SE LECT_0 PT 

461 ERROR_SMG_INVALID_DATA_LENGTH 
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Remarks 

DosSetSession sets one or both of the following structure elements related to a child session. The ele- 
ments can be set individually by the parent session, and either one can be changed without affecting the 
current setting of the other: 

selectlnd Sets the child session selectable or non-selectable. 

bondind Bonds the child session to the parent session. If the operator selects the parent session from 
the Task Manager, the child session is brought to the foreground. 

These elements only affect selections made by the operator from the switch list, not selections made by 
the parent session. When a parent session selects its own session, the parent session is brought to the 
foreground even if a bond is in effect. When a parent session selects a child session, the child session is 
brought to the foreground even if the parent session had set the child session to be non-selectable. 

DosSetSession may be issued by a process only for a child session it started with a DosStartSession 
request, specifying Related = 1. Neither the parent session nor any grandchild session may be the target 
of DosSetSession. 

A bond established between a parent session and a child session can be broken by reissuing 
DosSetSession and specifying either: 

bondind = 2 Breaks the bond between the parent session and the child session, 

bondind = 1 Establishes a bond with a different child session. In this case the bond with the pre- 

vious child session is broken. 

Assume a bond is established between session A and its immediate child session B. Assume another 
bond is established between session B and its immediate child session C. Now if the operator selects 
session A, session C is brought to the foreground. However, if session A selects its own session, session 
A is brought to the foreground. If session A selects session B, session C is brought to the foreground. In 
the latter case, the bond between B and C is honored. 

Assume a bond is established between session A and its immediate child session B, and assume B is 
non-selectable. The operator cannot select session B directly. However, if the operator selects session 
A, session B is brought to the foreground. 

A parent session can run in either the foreground or background when DosSetSession is issued. 

C Language 

typedef struct _STATUSDATA { /* stsdata */ 

USHORT Length; /* length of this data structure */ 

USHORT Selectlnd; /* Deleave setting unchanged, l=selectable 

2 c non-selectable */ 

USHORT Bondind; /* which session to bring to foreground */ 

> STATUSDATA; 

Idefine INCL_DOSSE$MGR 


USHORT rc = DosSetSession(SessID, StatusData); 


USHORT 

SessID; 

/* Session ID */ 

PSTATUSDATA 

StatusData; 

/* Session status data */ 

USHORT 

rc; 

/* return code */ 
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Assembler Language 

STATUSDATA struc 

stsdata_Length dw ? ; length of this data structure 
stsdata_SelectInd dw ? ; Deleave setting unchanged, ^selectable 
;2=non-se1ectable 

stsdata_BindInd dw ? ; which session to bring to foreground 

STATUSDATA ends 

EXTRN Dos Se t Ses s i on : FAR 
INCLJ30SSESMGR EQU 1 

PUSH WORD SessID ; Session ID 

PUSH® OTHER StatusData ; Session status data 

CALL DosSetSession 

Returns WORD 
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This call notifies OS/2 of a handler for a signal. It may also be used to ignore a signal or install a default 
action for a signal. 


DosSetSigHandler (Routine, PrevAddress, PrevActlon, Action, SlgNumber) 

Parameters 

Routine ( PFNSIGHANDLER ) - input 

Address of the entry point of routine that receives control when a signal equal to SigNumber is 
received. 

PrevAddress (PFNSIGHANDLER FAR *) - output 

Address of the previous signal handler. This operand may be coded as null (= 0), then it is ignored. 
PrevActlon (PUSHORT) - output 

Address of the previous signal action. Only values 0 to 3 are returned. This operand may be coded 
as null (= 0), then it is ignored. 

Action ( USHORT) — input 

Indicates what action to take when the specified signal is received: 

Value Definition 

0 The system default action is installed for the signal. 

1 The signal is to be ignored. 

2 The routine receives control when the SigNumber occurs. 

3 It is an error for any program to signal this SigNumber to this process. 

4 The current signal is reset without affecting the disposition of the signal. 

SigNumber ( USHORT) - input 

Signal number to be intercepted by this signal handler. The signal numbers defined are: 

Value Definition 

1 Ctrl-C (SIGINTR) 

3 Program terminated (SIGTERM) 

4 Ctrl-Break (SIGBREAK) 

5 Process flag A (SIGPFA) 

6 Process flag B (SIGPFB) 

7 Process flag C (SIGPFC) 

Note: Presentation Manager applications may not establish signal handlers for Ctrl-C and Ctrl- 
Break. Establishing a signal handler for Ctrl-C and Ctrl-Break is supported for 
VIO-Windowable and full-screen applications. 

The following chart indicates what signal to specify to cause the signal handler to get control for the 
CTRL-C and CTRL-Break key sequences in each of the keyboard modes (ASCII and Binary): 



ASCII Mode 

BINARY Mode 

CTRL-C 

SIGINTR 


CTRL-Break 

SIGINTR 

SIGBREAK 


rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

1 ERRORJNVALID^FUNCTION 

209 ERROR_INVALID_SIGNAL_NUMBER 

210 ERROR_THREAD_1_IN ACTIVE 
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Remarks 

When the signal indicated by SigNumber occurs, the signal handling routine receives control with: 

(SS:SP) Far return address 
(SS:SP+4) SigNumber being processed 

(SS:SP + 6) SigArg furnished on the DosFlagProcess request, if appropriate. 

Other than SS, SP, CS, IP and flags, all registers contain the same values they contained at the time the 
signal was received. The handler may exit by executing an intersegment return instruction, or by manu- 
ally setting the stack frame to some known state and jumping to some known location. If the former 
option is selected, execution resumes where it was interrupted, and all registers are restored to their 
values at the time of the interruption. 

The signal handler is given control under the first thread of a process, not a thread created by the 
DosCreateThread system request. It is invalid to issue this system call when thread 1 has terminated. If 
thread 1 terminates with other threads still active, all signals are reset to the default action. 

To return from the signal, the handler must remove the signal number and signal argument passed as 
parameters. For handlers written in most high-level languages, this is done automatically. A handler 
written in assembler language must execute a Far RET 4 instruction or its equivalent, to return to the 
caller. The signal handler may also reset the stack pointer to some previous valid stack frame and jump 
to some other part of the program. 

The values returned in PrevAddress and PrevAction are to be used for restoring the previous signal 
handler when the current process no longer wishes to intercept this signal. For Action = 4, no values are 
returned for PrevAddress or PrevAction. 

When a signal is issued from the base keyboard device driver in response to a Ctrl-C or Ctrl-Break key 
press, the default action terminates the process if the application did not install a signal handler for any 
signal numbers 1-4. 

For signals of type SIGINTR or SIGBREAK, a call to DosSetSigHandler also determines which process 
within the current session is signalled as a result of a device driver call to Device Helper Services for the 
SendEvent function and CTRL-C (or CTRL-BREAK) event type. (See the IBM Operating System/2 Version 
1.2 I/O Subsystems And Device Support Volume 7, Device Helper Services discussion). This process is 
known as the 'signal focus” for SIGINTR (or SIGBREAK) within its session. The signal focus for SIGINTR 
need not be the same process as the signal focus for SIGBREAK. The determination for signal focus 
follows. 

Initially, a session has no signal focus for SIGINTR (or SIGBREAK). A process becomes the signal focus 
for SIGINTR ( or SIGBREAK) within its session if it calls DosSetSigHandler with ActionCode equal to 1, 2, 
or 3. A process remains the signal focus until: 

• The process terminates. 

• The process calls DosSetSigHandler with ActionCode equal to zero. 

• Another process calls DosSetSigHandler with ActionCode equal to 1, 2, or 3. 

In the first two cases, the parent or its closest related ancestor process that has a handler installed for 
the appropriate signal becomes the focus. If no eligible process exists, the session ceases to have a 
signal focus for that signal. 

If a device driver makes a SendEvent call for CTRL-C or CTRL-BREAK and the current session has no 
focus for the corresponding signal, all processes in the session are signaled with SiGTERM to terminate. 
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Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction 
applies to DosSetSigHandler when coding in DOS mode: 

• The only signals recognized in DOS are SIGINTR (Ctrl-C) and SIGBREAK. 

• The option Action = 3 generates an “invalid signal number' 1 error. 

• If SigNumber is any value other than SIGINTR or SIGBREAK, then an “invalid signal number" error is 
generated. 

SIGINTR is fully supported, and SIGBREAK is related to SIGINTR. Therefore, if SIGINTR is specified, both 
SIGINTR and SIGBREAK are transferred to the SIGINTR handler. SIGBREAK is permitted as a coded 
value, but the request to set SIGBREAK is ignored. To be compatible in all environments, SIGBREAK and 
SIGINTR should be considered together in all cases. 


C Language 

^define INCL.DOSSIGNALS 


USHORT rc = DosSetSigHandler (Routine, PrevAddress, PrevAction, Action, 

SigNumber); 


PFNSIGHANDLER Routine; 

PFNSIGHANDLER FAR * PrevAddress; 
PUSHORT PrevAction; 

USHORT Action; 

USHORT SigNumber; 


/* Signal handler */ 

/* Previous handler (returned) */ 
lie Previous action (returned) ie/ 
/ie Indicate request type ie/ 

/ie Signal number of interest ie/ 


USHORT 


rc; 


/ie return code ie/ 


Assembler Language 

EXTRN DosSetSi gHandl er ; FAR 
INCL_DOSSIGNALS EQU 1 


PUSH® 

DWORD 

Routine 

PUSH@ 

DWORD 

PrevAddress 

PUSH@ 

WORD 

PrevAction 

PUSH 

WORD 

Action 

PUSH 

WORD 

SigNumber 

CALL 

DosSetSigHandler 


; Signal handler 
; Previous handler (returned) 
; Previous action (returned) 

; Indicate request type 
; Signal number of interest 


Returns WORD 


Example 

The following example illustrates the use of a user-defined flag to signal time-critical events. The main 
thread installs a routine, named FlagA_Handler(), as the signal handler for user-defined Flag A. It then 
creates a thread and blocks on a reserved RAM semaphore; this thread obtains its process ID and 
signals the main thread via Flag A. The main thread responds by executing the signal handler. 
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Idefine INCL DOSPROCESS 
#define INCLJJOSSIGNALS 
Idefine I NCL.DOS ERRORS 

linclude <os2.h> 

Idefine TIMEOUT 5O00L 

TID ThreadID; 

BYTE ThreadStack[4000] ; 

VOID API ENTRY FlagA_Handler(argl, arg2) /* Define signal handler */ 

USHORT argl; 

USHORT arg2; 

{ 

printf (“Handler for Flag A now running. \n") ; 
return; 

> 

VOID API ENTRY Thread_A() 

{ 

PIDINFO Pidlnfo; 

USHORT FlagArg; 

USHORT rc; 

DosGetPID(&Pi dlnfo) ; 

printf ("Process ID is %d\n", Pidlnfo. pid) ; 
if(!(rc = DosFlagProcess(PidInfo.pid, 

FLGP PID, 

PFLG_A, 

FlagArg))) 

printf("FlagA signal sent from ThreadA to main thread. \n"); 
else 

printf ("FI agProcess rc is %d\n". rc)/* Error processing on rc */; 
DosExi t ( EX I T_THREAD , /* Action Code */ 

RETURN_CODE) ; /* Result Code */ 


main() 

{ 

ULONG RamSem = 0L; 

ULONG far *Ram$emHandle - &RamSem; 

USHORT rc; 

i f ( ! (rc=DosSetSi gHandl er ( (PFNSIGHANDLER) FlagA_Handler. 

NULL, 

NULL, 

SIGA_ACCEPT, 

SIG_PFLG_A) ) ) 

printf ("Main thread has set FlagA handler. \n") ; 
else 

/* Error processing on rc */; 
i f ( ! (rc=DosSentReques t (RamSemHandl e , 

TIMEOUT))) 

pr i n t f ( " Semaph ore obt a i ned . \n " ) ; 
i f ( I ( DosCreat eThread ( (PFNTHREAD) Thread_A, 

&ThreadID, 

&ThreadStack [3999] ) ) ) 
printf ("ThreadA created.\n“); 

printf ("Main thread will now wait on a Ramsem for a while.\n H ); 
i f ( (rc=DosSemRequest (RamSemHandl e, 

TIMEOUT)) 

== ERRORJNTERRUPT) 

printf ("Main thread interrupted while waiting, rc is %d.\n", rc); 

} 
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This call allows a process to register an address to be used when a machine exception occurs. 


DosSetVec (VecNum, Routine, PrevAddress) 


Parameters 

VecNum (USHORT) - input 

Number of the vector to be serviced by this routine. Valid values are: 


Value 

Definition 

00 

Divide overflow 

04 

Overflow 

05 

Bound 

06 

Invalid opcode 

07 

Processor extension not available 

16 

Processor extension error. 


Routine (PFN) - input 

Address of a routine to be entered when the exception occurs. If this parameter is 0, any previous 
address is de-registered. 

PrevAddress (PFN) - output 

Address of the previous handler routine. This is provided so a handler may be set, then later 
restored to the previous handler. 

rc ( USHORT) — return 

Return code descriptions are: 

1 ERROR_INVALID_FUNCTION 

50 ERROR_NOT_SUPPORTED 

Remarks 

The DosSetVec process is analogous to setting an address in the interrupt vector table when running in 
8086 mode. 

Should an exception occur, and the process has registered a handler, that handler is entered as if its 
address had been stored in the CPU's interrupt vector, except that the interrupt is still enabled. If no 
address has been registered for that vector, the process terminates. 

When a process registers an exception handler for VecNum 7 (processor extension not available), the 
machine status word (MSW) for that process is set to indicate that a numeric processor extension (NPX) 
287 is not present in the machine. The Emulate bit is set and the Monitor Processor bit is reset This is 
done without regard for the true state of the hardware. 

When a process de-registers a handler for VecNum 7, the MSW is set to reflect the true state of the hard- 
ware. 


When an NPX287 exception is processing, the NPX287 status word is passed to the exception handler by 
being pushed on the stack before the exception handler is invoked. When the exception handler has 
completed execution, this word must be popped from the stack before an IRET is issued to return to the 
exception handler interface routine. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction 
applies to DosSetVec when coding for the DOS mode. 

VecNum = 7 not supported. 
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C Language 

Idefine INCLJHJSMISC 

USHORT rc = DosSetVec (VecNum, Routine, PrevAddress); 

USHORT VecNum; /* Function request code */ 

PFN Routine; /* Handler routine */ 

PFN PrevAddress; /* Previous handler address (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSetVec: FAR 
INCLJOSMISC EQU 1 

PUSH WORD VecNum function request code 

PUSH® OTHER Routine ; Handler routine address 

PUSHG DWORD PrevAddress ; Previous handler address (returned) 

CALL DosSetVec 

Returns WORD 
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This call sets the verify switch. 


DosSetVerify (VerifySetting) 


Parameters 

VerifySetting (USHORT) - input 

New state of Verify Mode for the requesting process as shown below: 

Value Definition 

0 Verify mode is not active. 

1 Verify mode is active. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

118 ERROR_INVALID_VERIFY_SWITCH 

Remarks 

When verify is active, OS/2 performs a verify operation each time it does a file write to assure proper 
data recording on the disk. Although disk recording errors are rare, this function has been provided for 
applications to verify the proper recording of critical data. 

C Language 

fdefine INCL_DOSFILEMGR 

USHORT rc = DosSetVerify (VerifySetting) ; 

USHORT VerifySetting; /* New value of verify switch */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSetVerify; FAR 
INCL_DOSFILEMGR EQU 1 

PUSH WORD VerifySetting ;New value of verify switch 
CALL DosSetVerify 

Returns WORD 
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This call returns the size of a segment 


DosSizeSeg (Selector, Size) 


Parameters 

Selector ( SEL ) - input 

Selector/segment of the segment for which size is to be determined. This must be the base selector 
in the case of a huge segment. 

Size (PULONG) - output 

Address of the returned segment size. For non-huge segments, size is in the range 0 through 64KB. 
For huge segments, size equals (NUMSEG < < 16) + ASIZE where NUMSEG and ASIZE are the last 
values passed successfully to DosAllocHuge or DosReallocHuge for this huge segment. 

rc (USHORT) — return 

Return code description is: 

0 NO_ERROR 

Remarks 

This function provides compatibility for family applications that must run in DOS or OS/2 mode. 
DosSizeSeg returns the actual size of memory allocated by a DosAllocSeg or DosAllocHuge request and 
is intended for use when the application is running in DOS mode, where allocations are rounded up to the 
next paragraph. 


C Language 

#define INCL_DOSMEMMGR 

USHORT rc = Dos$ize$eg(Selector, Size); 


SEL 

Selector; 

/* Selector/Segment */ 

PULONG 

Size; 

/* Size of segment (returned) */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN DosSizeSeg: FAR 
INCLJ50SMEMMGR EQU 1 

PUSH WORD Selector ;Selector/$egment 

PUSHG DWORD Size ;Size of segment (returned) 

CALL DosSizeSeg 

Returns WORD 
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Shutdown File Systems for Power Off 


This call locks out changes to all file systems and forces system buffers to disk in preparation for system 
power off. 


DosSIzeSeg (Reserved) 


Parameters 

Reserved ( ULONG ) - input 

Double-word whose value must be zero. 

rc (USHORT) - return 

Return code description is: 

0 NO_ERROR 

274 ERROR_ALREADY_SHUTDOWN 

87 ERRORJNVALID_PARAMETER 

Remarks 

DosShutdown may take several minutes to complete depending on the amount of data buffered. 

Other API function calls that change file system data called while the system is shutdown will either 
return the error ERROR_ALREADY_SHUTDOWN or block permanently. 

It should be noted that it will not be possible to increase memory overcommit once the DosShutdown has 
been called. This means that in low memory situations some functions may fail due to a lack of memory. 
This is of particular importance to the process calling DosShutdown. All memory that the calling process 
will ever need should be allocated before calling DosShutdown. This includes implicit memory allocation 
that may be done on behalf of the caller by system functions. 

When DosShutdown returns successfully, it is safe to power the system off or to reboot it. 

C Language 

♦define INCL_DOSFI LEMGR 

USHORT rc = DosShutdown ( Reserved) ; 

ULONG Reserved; /* Reserved, must be set to zero */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosShutdown: FAR 
INCLJJOSFILEMGR EQU 1 

PUSH DWORD Reserved Reserved, must be set to zero 
CALL DosShutdown 

Returns WORD 
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This call suspends the current thread for a specified time. If the requested interval is 0, the call gives up 
the remainder of the current time slice. 


DosSleep (Timelnterval) 


Parameters 

Timelnterval (ULONG) - input 

Time interval in milliseconds until the thread is awakened. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

322 ERROR_TS_WAKEUP 

Remarks 

DosSleep suspends the current thread for the specified time period. The actual time it is asleep may be 
off by a clock tick or two, depending on the execution status of other threads running in the system. 

If the time is 0, the thread gives up the remainder of the current time slice and allows any other ready 
threads of equal priority to run with the current thread for its next slice. Because the amount of sleep 
time specified is 0, an immediate return with 0 delay is made if no other ready thread is found. However, 
DosSleep does not yield to a thread of lower priority. 

If the time is non-0, the time is rounded up to the resolution of the scheduler clock. 

If DosSleep is used to regularly poll an external source to determine the occurrence of some event, a 
time equal to the longest response interval should be used. 

For short time intervals, the rounding-up process combined with the thread priority interactions may 
cause a sleeping interval to be longer than requested. Also, when a process completes sleeping, it is 
scheduled for execution. But that execution could be delayed by hardware interrupts or by another 
thread running at a higher priority. A program should not use the DosSleep call as a substitute for a 
real-time clock because rounding of the sleep interval causes cumulative errors. 

Asynchronous timers can be started with DosTimerAsync and DosTimerStart. DosTimerAsync starts a 
one-shot asynchronous timer, and DosTimerStart starts a periodic interval timer. DosTimerStop is issued 
to stop these timers. 

Note: To ensure optimum performance, you should not use DosSleep in a single-thread Presentation 
Manager application. See WinStartTimer. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following 
restrictions apply to DosSleep when coding in DOS mode: 

• DosSleep accuracy can be in error by 0.5%. 

• DosSleep can degrade system performance of non-foreground program operations when DOS mode 
is in foreground. 
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DosSleep - 

Delay Process Execution 


FAPI 


C Language 

#define INCLJJOSPROCESS 

USHORT rc = DosSl eep(TimeInterval ) ; 

UL0N6 Timelnterval ; /* Interval size (in milliseconds) */ 

USHORT rc; /* return code */ 


Assembler Language 

EXTRN DosSleep: FAR 
INCL_DOSPROCESS EQU 1 

PUSH DWORD Timelnterval ; Interval size (in milliseconds) 
CALL DosSl eep 

Returns WORD 


Example 

The following example illustrates how to obtain the priority of a thread and how to change the priority. 
The main thread creates Thread2 and allows it to begin executing. Thread2 iterates through a loop that 
prints a line and then sleeps, relinquishing its time slice to the main thread. After one or two iterations 
by Thread2 t the main thread obtains Thread2's priority information and prints it. It then raises Thread2's 
priority to fixed-high, and increments the level by ten. Since Thread2 is now at a high priority, it imme- 
diately finishes its remaining iterations before relinquishing control on a long sleep; at this point, the 
main thread re-examines Thread2's priority and reports its new priority level. In this example, it is 
helpful to understand how the DosSleep calls are used either to relinquish control of the processor, or to 
keep a thread alive (see DosTimerAsync or DosTimerStart for alternatives to DosSleep). 

Idefine INCL_DOSPROCESS 

#include <os2.h> 


#define 

PRTYC FIXEDHIGH 

4 

/* Priority class; fixed-high */ 

#define 

PRTY DELTA 

10 

/* Priority delta: increase by 10 */ 

Idefine 

SEGSIZE 

4600 

/* Number of bytes requested in segment */ 

#define 

ALLOCFLAGS 

0 

/* Segment allocation flags - no sharing */ 

#def i ne 

SLEEPSHORT 

0L 

/* Sleep interval - 5 milliseconds */ 

#def i ne 

SLEEPLONG 

20L 

/* Sleep interval - 75 milliseconds */ 

Idefine 

RETURN CODE 

0 

/* Return code for DosExit() */ 


VOID API ENTRY Thread2() 

{ 

USHORT 1 ; 

/* Loop with four iterations */ 
for (i *»1; i<5; i++) 

{ 

printfC'In Thread2, i is now %d\n\ i); 

/** Sleep to relinquish time slice to main thread **/ 

DosSl eep (SLEEPSHORT); /* Sleep interval */ 

Dos Exi t ( EX I TJTHREAD . /* Action code - end a thread */ 

RETURN_CODE) ; /* Return code */ 

} 
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main() 


USHORT 

Priority; 

/ie Thread priority ie/ 

USHORT 

Class; 

/ie Priority class ie/ 

USHORT 

Level ; 

/ie Priority level */ 

SEL 

ThreadStackSel ; 

/ie Segment selector for thread stack ie/ 

PBYTE 

StackEnd; 

/ie Ptr. to end of thread stack ie/ 

USHORT 

rc; 



/* Allocate segment for thread stack; this is better than just */ 

/* declaring an array of bytes to use as a stack. Make pointer eos. */ 
rc ■ DosAllocSeg(SEGSIZE, /* Number of bytes requested */ 

&ThreadStackSel , fie Segment selector (returned) iej 

ALLOCFLAGS) ; /* Allocation flags */ 

StackEnd = MAKEP(ThreadStackSel f SEGSIZE-1) ; 


fie Start Thread2 ie/ 

i f ( 1 (DosCreateThread((PFNTHREAD) Thread2, /ie Thread address */ 

aThreadID, /ie Thread ID (returned) ie/ 

StackEnd))) /ie End of thread stack ie/ 

printf ("Thread2 created. \n“); 

/ieie Sleep to allow Thread2 to execute **/ 

if (! (DosSleep(SLEEPLONG))) /ie Sleep interval ie/ 

printf ("Slept a little to let Thread2 execute. \n“); 


/ieie Obtain Thread2’s priority information and report it ieie/ 
if(!(rc s DosGetPrty(PRTYS_THREAD, /ie Scope - single thread ie/ 

&Priority* /ie Address to put priority ie/ 

ThreadID))) /ie ID - thread ID ie/ 

{ 


/ie Extract priority class and level information ie/ 

Class = HIBYTE(Priority) ; 

Level = LOBYTE (Priority) ; 

printf ("Thread2: ID is %d. Priority Class is %d and Level is %d\n H , 


ThreadID, Class, Level); 

} 

/ieie Raise Thread2's priority ieie/ 
i f ( ! (rc s DosSetPrty(PRTYS_THREAD, 

PRTYC FIXEDHIGH, 

PRTY_DELTA, 

ThreadID))) 

{ 


/ie Scope - single thread ie/ 

/ie Prty class - fixed-high ie/ 

/ie Prty delta - increase by 10 ie/ 
/ie ID - thread ID ie/ 


/ie Obtain Thread2' new priority information and report it ie/ 
rc a OosGetPrty(PRTYS_THREAD, /ie Scope - single thread ie/ 

apriority, /ie Address to put priority */ 

ThreadID); /ie ID - thread ID ie/ 


/ie Extract priority class and level information ie/ 

Class = HIBYTE(Priority); 

Level = LOBYTE (Priority); 

printf ("Thread2: ID is %d. New Priority Class is %d and Level is %d\n“, 
ThreadID, Class, Level); 

} 

} 
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DosSMRegisterDD - 

Register Session Switch Notification 


Allows a device driver to register itself with the Session Manager. 


DosSMRegisterDD (RegisterData) 


Parameters 

RegisterData (PREGISTERDATA) - input 

Address of the structure containing the RegisterData necessary for this call. 

Length ( USHORT) 

Length of the data structure in bytes including Length itself. Length is 8 for OS/2 version 1.2. 
Notification (USHORT) 

Bit map that informs the session manager when to issue the notification IOCTL to the device 
driver. The bits of this word are defined as follows: 

Bit Description 

15-4 Reserved and must be set to zero. 

3 Session termination notification. Action = 8 

2 Post-Session restore notification. Action = 4 

1 Post-Session save notification. Action = 2 

0 Pre-Session save notification. Action = 1 

Action is the unsigned integer in the Action field of the notification IOCTL. This tells the device 
driver what is happening. Notice that the integers correspond to bits 0 to 3 being set. 

DDName (ULONG) 

Address of the device name, as an ASCIIZ string (ie. SCREENS, KBD$, etc.). 

rc (USHORT) — return 

Return code descriptions are: 

418 ERROR_SMGJNVALID_CALL 

461 ERROR_SMG_INVALID_DATA_LENGTH 

515 E R R O R_SM G_T 00_M AN Y_D DS 

516 ERR0R_SMGJNVALID_N0T!F1CATI0N 

Remarks 

The Session Manger calls the registered device driver during a session switch, based on the specific 
form of notifications required. 

The notification IOCTL passed to the device driver has the following format: 

Size Definition 

WORD DevlOCtl packet length, including the length itself 

WORD Screen switch notification type 

WORD Incoming session number 

WORD Outgoing session number. 

The device driver passes a bit map that informs the session manager when the device driver needs to be 
called. The possible phases are: 

Before a session save 

After a session save (before a restore) 

After a session restore 
After a session termination. 

The device drivers must issue this API only during their initialization phase. After the session manager 
has been initialized, it rejects all further calls to this API, returning ERROR_SMGJNVALID_CALL. 
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C Language 

# define INCL.DOSFILEMSR 

USHORT rc = DosSMRegisterDD(RegisterData) ; 

PREGISTERDATA RegisterData; /* Data packet */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSMRegisterDD: FAR 
INCLJJOSFILEMGR EQU 1 

RUSK® OTHER RegisterData ;Data packet 

CALL DosSMRegisterDD 

Returns WORD 
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This call allows a program to start another program in a session. 


DosStartSession (StartData, SessID, ProcID) 


Parameters 

StartData (PSTARTDATA) - input 

Address of the start session structure: 

length ( USHORT) 

Length in bytes of the data structure, including length. A length of 24 bytes may be specified for 
OS/2 1.0 applications, or for applications that do not take advantage of the environment or win- 
dowing data. 

A length of 30 bytes may be specified for OS/2 applications that want to use only the environ- 
ment and inheritance features. 

A length of 50 bytes may be selected for applications that want to use all the functions provided 
by DosStartSession. However, a length of 50 bytes is not allowed if the Session Manager detects 
that the Presentation Manager is not present. 

related ( USHORT) 

Specifies whether the session created is related to the calling session, with the following values: 

Value Definition 

0 New session is an independent session (not related). 

1 New session is a child session (related). 

An independent session is not a child session and cannot be controlled by the calling program. 

It cannot be specified as the target of DosSelectSession, DosSetSession, or DosStopSession. 
Note that termq is ignored for independent sessions, and the value of zero is returned for the 
SessID and ProcID parameters. 

The calling program (parent session) may specify a child session as the target of 
DosSelectSession, DosSetSession, and DosStopSession, for related sessions. The SessID and 
ProcID parameters, and termq, are applicable only when related = 1 is specified. 

Note also that for related sessions, although a parent session/child session relationship is estab- 
lished, a parent process/child process relationship is not established. 

fgbg (USHORT) 

Specifies whether the new session should be started in the foreground or background: 

Value Definition 

0 Start session in foreground. 

1 Start session in background. 

traceopt (USHORT) 

Specifies tracing options for the program started in the new session: 

Value Definition 

0 T race off. 

1 Trace on; no notification of descendants. 

2 Trace on; all descendant sessions. 

For traceopt = 2, a termination queue must be supplied and related set to 1. Refer to "Debugger 
Considerations” in the Remarks section for additional information. 

pgmtltle (PSZ) 

A far pointer to an ASCIIZ string containing the program title. The string can be up to 61 bytes 
long, including the terminating byte of 0. If pgmtitle is zero or a NULL pointer, then 
DosStartSession defaults the program title to the name pgmname points to, minus any leading 
drive and path information. 
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Start Session 


pgmname (PSZ) 

Can be one of the following: 

9 A far address to a NULL string. 

• A NULL pointer (a far address equal to zero). 

• An address of an ASCIIZ string containing the fully qualified drive, path, and file name of the 
program to be loaded. 

If pgmname is a far address to a NULL string, or if it is a NULL pointer, the program name 
defaults to the command processor defined in the CONFIG.SYS/PROTSHELL statement. For 
example, if PROTSHELL= PMSHELL.EXE CMD.EXE, the program name defaults to CMD.EXE. 

pgminputs (PBYTE) 

A far pointer to an ASCIIZ string containing the input arguments to be passed to the program. 

Note: The maximum value allowed for the combined length of pgmname and pgminputs is 1024 
characters. For more information on pgmname and pgminputs, see "Program 
Name/Program Input Considerations:" in the Remarks section. 

termq (PBYTE) 

Can be one of the following: 

• A far address to a NULL string. 

• A NULL pointer (a far address equal to zero). 

• A far pointer to an ASCIIZ string containing the fully qualified path and file name of an OS/2 
queue created by a DosCreateQueue request. See "Parent/Child Termination 
Considerations" in the Remarks section for additional information. 

environment (PBYTE) 

Can be one of the following: 

• A far address to a NULL string. 

• A NULL pointer (a far address equal to zero). 

• A far pointer to an ASCIIZ environment string (see DosExecPgm) to be passed to the 
program started in the new session; it may be used for independent or related 
DosStartSession calls. 

When environment = 0 (content of the string is not specified and a far address of 0 is passed), 
the program in the new session inherits the environment of the Shell if inheritopt = 0, or the 
environment of the program issuing the DosStartSession call if inheritopt = 1. 

Inheritopt (USHORT) 

Specifies whether the program started in the new session should inherit the calling process' 
environment and open file handles: 

Value Definition 

0 Inherit from Shell process 

1 Inherit from calling process. 

Note that inheritopt is applicable whether the session being started is an independent or related 
session. After the DosStartSession request has completed, the new program’s parent process is 
the Shell, not the process that issued the DosStartSession call. See "Parent/Child 
Relationships" in the Remarks section. 

sessiontype (USHORT) 

Type of session that should be created for this program: 

Value Definition 

0 Use pgmhandle or allow the Shell to establish the session type 

1 Full screen session 

2 Text-windowed session for programs using the Base Video Subsystem 

3 Presentation Manager session. 

iconflle (PSZ) 

Can be one of the following: 

• A far address to a NULL string 

• A NULL pointer (a far address equal to zero) 
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• A far pointer to an ASCIIZ string containing the fully qualified drive, path and file name of an 
icon definition. 

The system provides an icon for windowed applications if an icon file name is not provided on 
the DosStartSession call. 

pgmhandle (ULONG) 

This is either 0 or the program handle returned by the WinAddProgram call. The program 
handle identifies the program in the installation file to be started, the program title, the session 
type, and the initial window size and position. However, information may be specified on the 
DosStartSession call to override the information in the installation file for this invocation of the 
program. 

See “Program Handle Considerations:" in the Remarks section for more information, 
pgmcontro! ( USHORT) 

Specifies the initial state for a windowed application. This parameter is ignored for full-screen 
sessions. The initial window state may be defined as a combination of the following bit values: 

Bit Description 

15 Use specified position and size. 

14-4 Reserved and must be set to zero. 

3 No auto close (for windowed session only). 

2 Minimize. 

1 Maximize. 

0 Invisible. 

Inltxpos ( USHORT) 

Initial X coordinate in pels for the initial session window. Coordinates (0,0) indicate the bottom 
left corner of the display. This parameter is ignored for full-screen sessions. 

Inltypos ( USHORT) 

Initial Y coordinate in pels for the initial session window. Coordinates (0,0) indicate the bottom 
left corner of the display. It is ignored for full-screen sessions. 

Enttxslze {USHORT) 

Initial X extent in pels for the initial session window. It is ignored for full-screen sessions, 
fnltysize ( USHORT) 

Initial Y extent in pels for the initial session window. It is ignored for full-screen sessions. 
SessID ( PUSHORT) - output 

Address of the session ID associated with the child session created. SessID is returned only when 
the value specified for related is 1. The SessID returned can be specified on subsequent calls to 
DosSelectSession, DosSetSession, and DosStopSession. 

ProcID {PUSHORT) - output 

Address of the process ID associated with the child process created. ProcID is returned only when 
the value specified for related is 1. The ProcID returned may not be used on any OS/2 calls, for 
example, DosSetPrty, that require a parent process/child process relationship. See “Parent/Child 
Relationships" in the Remarks section. 

rc {USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

370 ERROR_SMG_NO_SESSIONS 

418 ERROR_SMG_INVALID_CALL 

453 ERROR_SMG_INVAUD~START_MODE 

454 ERROR_SMGJNVALID_RELATED_OPT 

457 ERROR_SMG_START_IN_BACKGROUND 

460 ERROR_SMG_PROCESS_NOT_PARENT 

461 error_smgjnvalid_data1ength 

478 ERROR_SMG_INVALID_TRACE_OPTION 

491 ERROR_SMGJNVALID_PROGRAM_TYPE 

492 ERROR_SMG_INVALID_PGM_CONTROL 
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493 ERROR_SMGJNVALIDJNHERIT_OPT 

503 ERROR_SMGJNVALID_DEBUG_PARMS 

Any error code returned from DosOpen, DosLoadModule, and DosExecPgm is also possible from 
DosStartSession. 

Remarks 

When a length of 24 bytes is specified, DosStartSession assumes the iconfile, pgmhandle, sessiontype, 
pgmcontrol, initxpos, initypos, initxsize, and initysize parameters to be 0. A value of 0 allows the Shell to 
establish the program title, icon definition, session type, program control, window size, and window posi- 
tion for the specified program. 

Foreground/Background Considerations: If fgbg = 0 is specified, and if neither the calling program nor 
any of its descendant sessions is executing in the foreground, the new session is started in the back- 
ground. The ERROR_SMG_STARTJNJBACKGROUND error code is also returned in this case. The fore- 
ground session for windowed applications is the session of the application that owns the window focus. 

Parent/Child Relationships: When related = 1 is specified, DosStartSession establishes a parent 
session/child session relationship. A parent process/child process relationship is not established. The 
parent process is the Shell process, just as if the operator had started the program from the Shell menu. 
The ProcID returned by DosStartSession may not be used by any OS/2 calls (for example, DosSetPrty) 
that require a parent process/child process relationship. Once a process has issued a DosStartSession, 
specifying related = 1, no other process within that session may issue related DosStartSession calls until 
all the dependent sessions have terminated. 

Debugger Considerations: Debuggers may want to debug all processes associated with an application, 
no matter how the process was started (DosExecPgm or DosStartSession). A special trace option, 
traceopt = 2, has been provided for this purpose. When traceopt = 2 is specified, the debugger must 
also supply the name of an existing queue as the termination queue name and related = 1 on the 
DosStartSession call. 

The Session Manager notifies the debugger whenever a new session is created through DosStartSession 
from the initial session started with traceopt = 2 or from any descending session. The queue is posted 
regardless of how the new session is started: related, independent, with or without inheritance, and is 
executed for tracing. It is the responsibility of the debugger to resume the new process' execution 
through DosPtrace. 

The debugger must issue DosReadQueue to receive notification when a child session is created. The 
word containing the request parameter returned by DosReadQueue is one. The data element structure 
returned has the following format: 


Size 

Definition 

WORD 

Session ID 

WORD 

Process ID 

WORD 

Parent Session ID 

WORD 

Parent Process ID 


DosReadQueue, with the NoWait parameter set to zero, should be issued by the debugger. This is the 
only process that has addressability to the notification data element. After reading and processing the 
data element, the debugger must free the segment containing the data element using DosFreeSeg. 

The debugger may use DosSelectSession to switch itself or any descendant session into the foreground 
whenever the current foreground session is a descendant of the debugger. 

Some debuggers may enhance usability by using more than one display. Therefore, when a debugger 
registers with the Session Manager by using a traceopt of 2, the debugger is allowed to update the phys- 
ical video buffer in the range of B000-B7FF, as long as the foreground session is a descendant of the 
debugger. The debugger is not allowed to update the physical video buffer when a session is switched 
into the foreground that is not a descendant of the debugger or when a popup occurs. 
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Program Name/Program Input Considerations: The program identified by pgmname is executed directly 
with no intermediate secondary command (CMD.EXE) process. Alternatively, the program can be exe- 
cuted indirectly through a secondary command (CMD.EXE) process by specifying CMD.EXE for pgmname 
and by specifying either /C or /K followed by the drive, path, and file name of the application to be loaded 
for pgminputs. If the /C parameter is inserted at the beginning of the pgminputs string, the session termi- 
nates when the application program terminates. If the /K parameter is inserted at the beginning of the 
pgminputs string, the operator sees the OS/2 command line prompt displayed when the application termi- 
nates. The operator can then either enter the name of another program or command to execute or enter 
the OS/2 EXIT command to terminate the session. 

When the pgmname is accessed with a far address of 0 or the ASCIIZ string is null, the program specified 
as a parameter to the Shell in the PROTSHELL statement in the CONFIG.SYS file is executed and passed 
the specified pgminputs. This is the OS/2 mode command processor (CMD.EXE) by default. 

When pgmname is equal to the command processor named on the PROTSHELL statement in 
CONFIG.SYS, or when the pgmname = NULL and length = 24 or 30 bytes, either the command processor 
named in CONFIG.SYS or the default CMD.EXE is started within the same session as the caller of 
DosStartSession. 

Program Handle Considerations: If a process issues a DosStartSession specifying only the program 
handle, it must change to the working directory before it issues the DosStartSession, and start the new 
process inherited. If a process is started with inheritopt = 0, that process must change to the correct 
directory. 

Parent/Child Termination Considerations: A parent session has only one termination queue. The parent 
creates the termination queue before it issues its first DosStartSession call specifying the name of the 
queue. An application can use the termination queue for another purpose by passing a unique request 
parameter through the DosWriteQueue/DosReadQueue interface. Request parameter values 0 through 
99 are reserved for OS/2. Request parameter values greater than 99 are available for application use. 

If a parent session specifies the termq parameter on more than one DosStartSession call, the parameter 
is ignored on subsequent calls. Once a parent establishes a termination queue, the queue is posted 
when any child session terminates. The queue is posted regardless of who terminates the child session 
(for example, child, parent, or operator) and whether the termination is normal or abnormal. The termq 
data element structure has the following format: 

Size Description 

WORD Session ID of child 

WORD Result code. 

When a child session terminates, the result code returned in the termq data element is the result code of 
the program specified by pgmname assuming either: 

1. The program is executed directly with no intermediate secondary command (CMD.EXE) process, or 

2. The program is executed indirectly through a secondary command (CMD.EXE) process and the /C 
parameter is specified. 

If the program is executed indirectly through a secondary command (CMD.EXE) process and the /K 
parameter is specified, the result code of the processed command is returned. 

When a child session running in the foreground terminates, the parent session becomes the foreground 
session. When a parent session terminates, any child sessions it created with DosStartSession, speci- 
fying related = 1, are terminated. When an independent session, created specifying related = 0, running 
in the foreground terminates, the Shell chooses the next foreground session. 

Descendant Considerations: A session started through DosStartSession may in turn issue 
DosStartSession. These rules apply: 

• The SessID specified on DosSelectSession, DosSetSession, and DosStopSession may be only the 
SessID of an immediate child session, not a grandchild session, and so forth. 
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• Suppose a bond is established between session A and its immediate child session B, and another 
bond is established between session B and its immediate child session C. When the operator selects 
session A, session C is brought to the foreground. See DosSetSession for a description of what 
establishing a bond means. 

• When a session terminates, all of its descendants (children, grandchildren, and so forth) are termi- 
nated. 


C Language 

typedef struct _STARTDATA { /* stdata */ 


USHORT 

cb; 

/* 

USHORT 

Related; 

/* 

USHORT 

FgBg; 

/* e=! 

USHORT 

TraceOpt; 

/* 

PSZ 

PgmTitle; 

/* 

PSZ 

PgmName; 

/* 

PBYTE 

Pgmlnputs; 

/* 

PBYTE 

TermQ; 

/* 

PBYTE 

Envi ronment ; 

/* 

USHORT 

InheritOpt; 

/* 

USHORT 

SessionType; 

/* 

PSZ 

IconFile; 

/* 

ULONG 

PgmHandle; 

/* 

USHORT 

PgmControl ; 

He 

USHORT 

InitXPos; 

f* 

USHORT 

InitYPos; 

He 

USHORT 

InitXSize; 

lie 

USHORT 

InitYSize; 

!* 


} STARTDATA; 

Idefine INCL DOSSESMGR 


.) */ 


USHORT rc = DosStartSession(StartData, SessID, PID); 


PSTARTDATA 

Start Data; 

lie Start session data */ 

PUSHORT 

SessID; 

lie Session ID (returned) iel 

PUSHORT 

PID; 

lie Process ID (returned) iel 

USHORT 

rc; 

lie return code iel 
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Assembler Language 

STARTDATA st rue 

stdata_Length dw ? ; length of data structure in bytes 
stdatajtelated dw ? ;0=independent session, l=chi 1 d session 

stdata_FgBg dw ? ;0=start in foreground, l=start in background 

stdata_TraceOpt dw ? ;0*no trace, l=trace 

stdataJ’gmTitle dd ? ;address of program title 

stdata_PgmName dd ? ; address of program name 

stdata_PgmInputs dd ? ; input arguments 

stdata_TermQ dd ? ; address of program queue name 

stdata_Environment dd ? ; address of environment string 
stdata_InheritOpt dw ? ; inherit option (shell of program) 
stdata_SessionType dw ? ; session type (standard, windowed, ...) 
stdata_IconFile dd ? ; address of icon definition 
stdata_PgmHandle dd ? ; program handle 

stdata_PgmControl dw ? ; initial state of windowed application 
stdata_InitXPos dw ? ;x coordinate of initial session window 

stdata_InitYPos dw ? ;y coordinate of initial session window 

stdata_InitXSize dw ? ; initial size of x 

stdata_InitYSize dw ? ; initial size of y 

STARTDATA ends 

EXTRN DosStartSession: FAR 

INCL_DOSSESMGR EQU 1 

PUSH0 OTHER StartData ; Start session data 

PUSHO WORD SessID ;Session ID (returned) 

PUSHO WORD PID ^Process ID (returned) 

CALL DosStartSession 

Returns WORD 
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This call terminates a session previously started with DosStartSession. 


DosStopSession (TargetOptlon, SessID, Reserved) 


Parameters 

TargetOptlon ( USHORT) - input 

Specifies whether the session specified by SessID or all sessions should be terminated. 

Value Definition 

0 Terminate session specified. 

1 Terminate all child sessions and descendant sessions. 

SessID (USHORT) - input 

Session ID session to be terminated. The value specified must equal the SessID returned on a pre- 
vious DosStartSession call. SessID is ignored if TargetOption = 1. 

Reserved (ULONG) - input 
A doubleword of 0’s. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

369 ERROR_SMGJNVALID_SESSION_ID 

418 error7smg_invalid_call 

452 ERROR_SMG_SESSION_NOT_PARENT 

458 ERROR_SMGJNVALID_STOP_OPTION 

459 ERROR_SMG_BAD_RESERVE 

Remarks 

DosStopSession may be issued by a parent session only for a child session. The parent session cannot 
issue this call with itself as the target or a descendant of a child session as the target. However, if the 
child session specified with DosStopSession does have descendants, these sessions are also terminated. 

DosStopSession may terminate only child sessions originally started by the caller with DosStartSession 
specifying Related = 1. Sessions started as independent sessions cannot be stopped by this call. 

A parent session may be running in either the foreground or background when DosStopSession is issued. 
If a child session is running in the foreground at the time it is stopped, the parent session becomes the 
foreground session. DosStopSession breaks any bond that was established between the parent session 
and child session by a DosSetSession request. 

The process running in the session specified on the DosStopSession call may refuse to terminate. 
DosStopSession returns a normal return code in this case. The only way to ensure that a target session 
has terminated is to wait for notification of its demise by a termination queue created with a 
DosStartSession request. 

C Language 

# define INCI_D0SSE$MGR 

USHORT rc = DosStopSession(TargetOption, SessID, Reserved); 

USHORT TargetOption; /* Target option */ 

USHORT SessID; /* Session ID */ 

ULONG 0; /* Reserved (must be zero) */ 

USHORT rc; fie return code */ 
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DosStopSession - 
Stop Session 


Assembler Language 

EXTRN DosStopSession: FAR 
INCL_DQSSESMGR EQU 1 

PUSH WORD TargetOption ; Target option 

PUSH WORD SessID ;Session ID 

PUSH DWORD 0 ; Reserved (must be zero) 

CALL DosStopSession 

Returns WORD 
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fapi DosSub Alloc - 

Suballocate Memory within Segment 


This call suballocates portions of a segment allocated by DosAllocSeg or DosAllocShrSeg, and initialized 
by DosSubSet. 


DosSub A Hoc (SegSelector, BlockOffset, Size) 


Parameters 

SegSelector (SEL) - input 

Data segment selector that allocates the memory. 

BlockOffset (PUSHORT) - output 

Address of the allocated block offset. 

Size (USHORT) - input 

Memory block size requested in bytes. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

311 ERROR_DOSSUB_NOMEM 

313 ERROR_DOSSUB_BADSIZE 

Remarks 

Before a segment allocated by DosAllocSeg or DosAllocShrSeg can be suballocated f it must first be ini- 
tialized for suballocation by a call to DosSubSet. 

Allocation size must be a multiple of four bytes. Otherwise, it is rounded up to a multiple of four bytes. 
The maximum value for the size parameter is the size that was set with DosSubSet minus 8. Note that no 
paragraph (16-byte) alignment is required; all requests are serviced on a byte alignment basis. 

A suballocated block of memory in a suballocated segment is freed by a call to DosSubFree. 


C Language 

Idefine INCL_DOSMEMMGR 


USHORT rc = DosSubAlloc (SegSelector, BlockOffset, Size); 


SEL 

PUSHORT 

USHORT 

SegSelector; 

BlockOffset; 

Size; 

/* Segment selector */ 

/* Block Offset (returned) 
/* Size of requested block 

USHORT 

rc; 

/* return code */ 

Assembler Language 

EXTRN DosSubAlloc: FAR 
INCLJOSMEMMGR EQU 1 


PUSH WORD SegSelector 
PUSH? WORD BlockOffset 
PUSH WORD Si ze 

CALL DosSubAlloc 

; Segment selector 
; Block Offset (returned) 

;Size of requested block 


*/ 

*/ 


Returns WORD 
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DosSubFree - 

Free Memory Suballocated Within Segment 


FAPI 


This call frees memory previously allocated by DosSubAlloc. 


DosSubFree (SegSelector, BlockOffset, Size) 

Parameters 

SegSelector (SEL) - input 
Data segment selector. 

BlockOffset ( USHORT) - input 

Memory block offset. The value specified must equal the BlockOffset returned on a previous 
DosSubAlloc call. 

Size ( USHORT) - input 

Size, in bytes, of the block to be freed. 

re (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

312 ERROR_DOSSUB_OVERLAP 

313 ERROR_DOSSUB_BADSIZE 

Remarks 

DosSubFree specifies the offset of a block of memory previously suballocated by a DosSubAlloc request. 
If the block specified overlaps memory in the segment that is not suballocated, an error is returned. Like 
DosSubAlloc, the size parameter must be a multiple of four bytes; otherwise, it is rounded up to a mul- 
tiple of four bytes. 

The allocated segment is freed by calling DosFreeSeg. 

C Language 

Idefine INCL_DO$MEMMGR 

USHORT rc « DosSubFree(SegSelector, BlockOffset, Size); 

SEL SegSelector; /* Segment selector */ 

USHORT BlockOffset; /* Offset of memory block to free * / 

USHORT Size; /* Size of block in bytes */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSubFree: FAR 
INCL_DO$MEMMGR EQU 1 

PUSH WORD SegSelector ; Segment selector 

PUSH WORD BlockOffset ; Offset of memory block to free 

PUSH WORD Size ; Si ze of block in bytes 

CALL DosSubFree 

Returns WORD 
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fapi DosSubSet - 

Initialize or Set Allocated Memory 


This call is used to initialize a segment or to reset a reallocated segment for suballocation. 


DosSubSet (SegSelector, Flags, Size) 


Parameters 

SegSelector (SEL) - input 

Target data segment selector. 

Flags (USHORT) - input 

0 = Increasing the size of a segment already initialized. 

1 = Initializing a segment. 

Size (USHORT) - input 
Segment size in bytes. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

310 ERROR_DOSSUB_SHRINK 

313 ERROR_DOSSUB_BADSIZE 

314 ERROR_DOSSUB_BADFLAG 

Remarks 

To initialize a segment for suballocation, issue DosSubSet before issuing DosSubAlloc and set Flags = 1. 
The segment must have been allocated with DosAllocSeg or DosAllocShrSeg. 

If a segment allocated by a DosAllocSeg call has already been set for suballocation, and a call to 
DosSubAlloc returns Error_DOSSUB_NOMEM, the segment’s size can be increased by a call to 
DosReallocSeg. After reallocation, the segment must be reset by a DosSubSet. Failure to reset the 
segment after changing its size can yield unpredictable results. 

The size parameter should be a multiple of four bytes, or it is rounded up to a multiple of four. Note in 
DosSubSet, a size parameter of 0 indicates the segment is 64KB, while in DosSubAlloc and DosSubFree, 
a size parameter of 0 is an error. Other than this special case of 0 meaning 64KB, the minimum size that 
can be set is 12 bytes. 


C Language 

♦define INCL_DOSMEMMGR 

USHORT rc = DosSubSet (SegSelector, Flags, Size); 


SEL 

SegSelector; 

/* Segment selector */ 

USHORT 

Flags; 

/* Parameter flags */ 

USHORT 

Size; 

/* Size of a block */ 

USHORT 

rc; 

/* return code */ 
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DosSubSet - 

Initialize or Set Allocated Memory 


FAPI 


Assembler Language 

EXTRN DosSubSet: FAR 
INCL_DOSMEMMGR EQU 1 

PUSH WORD SegSelector ; Segment selector 

PUSH WORD Flags ; Parameter flags 

PUSH WORD Size ;Size of a segment 

CALL DosSubSet 

Returns WORD 
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DosSuspendThread - 
Suspend Thread Execution 


This call temporarily suspends execution of another thread within the current process until a 
DosResumeThread call is issued. 


DosSuspendThread (ThreadID) 


Parameters 

ThreadID ( TID ) - input 

Thread ID to be suspended. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

309 ERRORJNVALID_THREADID 

Remarks 

A thread's execution is suspended when another thread in its process issues DosSuspendThread, speci- 
fying the ID of the target thread. The thread may not be suspended immediately because it may have 
locked some system resources that have to be freed first. However, the thread is not allowed to execute 
further application program instructions until a corresponding DosResumeThread is issued. 

DosSuspendThread permits the suspension of only one other thread within the current process. If a 
thread needs to disable all thread switching within its process so the calling thread can execute time- 
critical code, it uses DosEnterCritSec and DosExitCritSec calls. 

C Language 

Idefine INCL_D0SPR0CESS 

USHORT rc = DosSuspendThread (Thread I D) ; 

TID ThreadID; /* Thread ID */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosSuspendThread : FAR 
INCL_D0SPR0CES$ EQU 1 

PUSH WORD ThreadID ; Thread ID 

CALL DosSuspendThread 

Returns WORD 

Example 

The following example shows how to suspend and resume execution of a thread within a process. The 
main thread creates Thread2 and allows it to begin executing. Thread2 Iterates through a loop that prints 
a line and then sleeps, relinquishing its time slice to the main thread. After one iteration by Thread2, the 
main thread suspends Thread2 and then resumes it. Subsequently, Thread2 completes the remaining 
three iterations. 
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DosSuspendThread - 
Suspend Thread Execution 


Idefine INCL_D0SPR0CES$ 

^include <os2.h> 

Idefine SEGSIZE 4000 /* Number of bytes requested in segment */ 

#define ALLOCFLAGS 0 /* Segment allocation flags - no sharing */ 

#define SLEEPSHORT 5L /* Sleep interval - 5 milliseconds */ 

#define SLEEPLONG 75L /* Sleep interval - 75 milliseconds */ 

^define RETURN_CODE 0 /* Return code for DosExitO */ 

VOID API ENTRY Thread2() 

{ 

USHORT i ; 

/* Loop with four iterations */ 
for(i=l; i <5; i++) 

{ 

printf (“In Thread2, i is now %d\n" , i); 

/* Sleep to relinquish time slice to main thread */ 

DosSleep(SLEEPSHORT) ; /* Sleep interval */ 

DosExit(EXIT_THREAD, /* Action code - end a thread */ 

RETl)RN_CODE) ; /* Return code */ 

mai n() 

{ 

TID ThreadIO; 

SEL ThreadStackSel ; 

PBYTE StackEnd; 

USHORT rc; 

/** Allocate segment for thread stack; make pointer to end of stack. **/ 
/** We must allocate a segment in order to preserve segment protection **/ 
/** for the thread. **/ 

rc ** DosAllocSeg (SEGSIZE, /* Number of bytes requested */ 

&ThreadStackSel , /* Segment selector (returned) */ 

ALLOCFLAGS); /* Allocation flags - no sharing */ 

StackEnd = MAKEP(ThreadStackSel , SEGSIZE-1); 

/** Start Thread2 **/ 

i f ( ! (rc=DosCreateThread ( (PFNTHREAD) Thread2, /* Thread address */ 

&ThreadID, /* Thread ID (returned) */ 

StackEnd))) /* End of thread stack */ 
printf("Thread2 created. \n“) ; 

/* Sleep to relinquish time slice to Thread2 */ 
if (! (DosSleep(SLEEPSHORT))) /* Sleep interval */ 

printf (“Slept a little to let Thread2 execute. \n") ; 

/***** Suspend Thread2, do some work, then resume Thread2 *****/ 
i f ( i (rc=DosSuspendThread(ThreadID) ) ) /* Thread ID */ 

pr i nt f ( “Thread2 SUSPENDED . \n " ) ; 

printf (“Perform work that will not be interrupted by Thread2.\n“) ; 
i f ( ! (rc=DosResumeThread(ThreadID) ) ) /* Thread ID */ 

printf(“Thread2 RESUMED. \n“); 
printf (“Now we may be interrupted by Thread2.\n“) ; 

/* Sleep to allow Thread2 to complete */ 

DosSleep(SLEEPLONG) ; /* Sleep interval */ 


/* Thread identification */ 

/* Segment selector for thread stack */ 
/* Ptr. to end of thread stack */ 
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DosTimerAsync — 
Start Asynchronous Time Delay 


This call starts a timer that runs asynchronously to the thread issuing the request and clears a system 
semaphore when the specified interval expires. 


DosTimerAsync (Timelnterval, SemHandle, Handle) 


Parameters 

Timelnterval (ULONG) - input 

Number of milliseconds (rounded up to the next clock tick) that passes before the semaphore is 
cleared. 

SemHandle ( HSEM ) - input 

Handle of the system semaphore used to communicate the time out to the calling thread. This 
semaphore should be set by DosSemSet before DosTimerAsync is called. 

Handle (PHTIMER) - output 

Address of the timer handle. This handle may be passed to DosTimerStop to stop this timer before 
its time interval expires. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

323 ERROR_TS_SEM HANDLE 

324 ERROR J-SJslOTI M E R 


Remarks 

DosTimerAsync is used to wait for a single asynchronous time. The thread waits for the time out by 
issuing a DosSemWait. 

This function is the asynchronous analog of DosSleep. This function allows a thread to start a timer while 
it is performing another task. This timer can be canceled by calling the DosTimerStop function with the 
timer handle returned by DosTimerAsync. 

If another time out is needed, the semaphore is set and DosTimerAsync is reissued. To ensure reliable 
detection of the timer expiration, the system semaphore should be set prior to calling DosTimerAsync. 

To set a periodic interval timer, see DosTimerStart. 


C Language 

# define INCL_DO$DATETIME 


USHORT rc = DosTimerAsync (Timelnterval , SemHandle, Handle); 


ULONG 

Timelnterval ; 

/* 

HSEM 

SemHandle; 

/* 

PHTIMER 

Handle; 

/* 

USHORT 

rc; 

/* 


Interval size (in milliseconds) */ 
System semaphore handle */ 

Timer handle (returned) */ 

return code */ 
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DosTimerAsync - 

Start Asynchronous Time Delay 


Assembler Language 

EXTRN DosTimerAsync: FAR 
INCL_DOSDATETIME EQU 1 

PUSH DWORD Timelnterval ; Interval size (in milliseconds) 
PUSH DWORD SemHandle ; System semaphore handle 
PUSH@ WORD Handle ; Timer handle (returned) 

CALL DosTimerAsync 

Returns WORD 


Example 

The following example sets an asynchronous one-shot timer for one second. It then sets an asynchro- 
nous recurring timer with a one-second interval, reporting each time an interval elapses. Finally, it stops 
the recurring timer. 

#define INCL DOSDATETIME 
#define INCLJJOSSEMAPHORES 

finclude <os2.h> 

Idefine SEM_NAME “\\SEM\\timer.sem ,, /* Semaphore name */ 

#define TIME_I NTERVAL 10OOL /* Timer interval (in milliseconds) */ 

mai n () 

{ 

HSEM SemHandle; 

HTIMER TimerHandle; 

USHORT i ; 

USHORT rc; 

/* Create system semaphore to be used by timers */ 

DosCreateSem(CSEM_PUBLIC, /* Ownership - nonexclusive */ 

&SemHandle, /* Semaphore handle (returned) */ 

SEM_NAME) ; /* Semaphore name */ 

/* Set the semaphore, then start a one-shot timer */ 
if (!DosSemSet( SemHandle)) /* Semaphore handle */ 

printf ("Semaphore set.\n"): 

i f ( I ( rc=DosT i merAsync (TIME_I NTERVAL , /* Timer interval */ 

SemHandle, /* Semaphore handle it/ 

&TimerHandle))) /* Timer handle (returned) it/ 

printf ("One shot timer for %f seconds started. \n u , T I ME J NTERVAL/ 1000.0); 

/it Report when timer expires (other work may be done here) it/ 
if (IDosSemWait (SemHandle, /* Semaphore handle it/ 

SEM_INDEFINITE_WAIT)) /it Timeout period - indefinite it/ 

printf ("Time interval has elapsed.\n"); 

/it Start a recurring timer it/ 

i f ( ! (rc=DosTimerStart(TIME_I NTERVAL, /* Timer interval it/ 

SemHandle, /* Semaphore handle */ 

&TimerHandle))) /it Timer handle (returned) it/ 

printf ("Recurring timer with %f second interval started. \n", 

T IME_I NTERVAL/ 1000 . 0) ; 

/it it/ 

for(i«l; i<4; i++) 

if ( ! DosSemSetWai t (SemHandle, /it Semaphore handle */ 

SEM_INDEFINITE_WAIT)) /* Timeout period - indefinite */ 
printf ("Recurring timer cleared semaphore %d times.\n", i); 
if (!(rc=DosTimer$top (TimerHandle))) /* Timer handle it/ 

printf ("Recurring timer has been stopped. \n" ) ; 

} 
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DosTimerStart - 
Start Periodic Interval Timer 


This call starts a periodic interval timer that runs asynchronously to the thread Issuing the request. The 
semaphore is continually cleared at the specified time interval until the timer is turned off by 
DosTimerStop. 


DosTimerStart (Timelnterval, SemHandle, Handle) 


Parameters 

Timelnterval ( ULONG ) - input 

Number of milliseconds (rounded up to the next clock tick) that passes before the semaphore is 
cleared. 

SemHandle ( HSEM ) - input 

Handle of the system semaphore used to communicate the time out to the calling thread. This 
semaphore should be set by DosSemSet before the next clear by the timer. 

Handle ( PHTIMER ) - output 

Address of the timer handle. This handle may be passed to DosTimerStop to stop the periodic timer. 

rc (I JSHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

323 ERROR_TS_SEMHANDLE 

324 ERROR_TS_NOTIMER 


Remarks 

DosTimerStart allows a timer to start and run asynchronously to a thread. A timer interval is canceled by 
using the timer handle in the DosTimerStop call. This prevents the semaphore indicated in the 
DosTimerStart call from being sent notifications. 

The application detects the expirations of the timer when the semaphore is set prior to the next expiration 
of the timer. When an application waits for this semaphore to clear, more than one clearing of the timer 
may occur before the application resumes execution. If it is necessary to determine the actual elapsed 
time, the Global Information Segment milliseconds field can be saved by a DosGetlnfoSeg request before 
calling DosTimerStart. This saved value is compared to the current value when the process resumes. 


C Language 

#define INCUJOSOATETIME 


USHORT rc s DosTimerStart(TimeInterval , SemHandle, Handle); 


ULONG 

HSEM 

PHTIMER 

USHORT 


Timelnterval ; 

/* 

SemHandle; 

/* 

Handle; 

/* 

rc; 

/* 


Interval size (in milliseconds) */ 
System semaphore handle */ 

Timer handle (returned) */ 

return code */ 


Assembler Language 

EXTRN DosTimerStart: FAR 
INCLJJOSDATETIME EQU 1 

PUSH DWORD Timelnterval ; Interval size (in milliseconds) 
PUSH DWORD SemHandle ; System semaphore handle 
PUSH® WORD Handle ; Timer handle (returned) 

CALL DosTimerStart 

Returns WORD 
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DosTimerStart - 

Start Periodic Interval Timer 


Example 

The following example sets an asynchronous one-shot timer for one second. It then sets an asynchro- 
nous recurring timer with a one-second interval, reporting each time an interval elapses. Finally, it stops 
the recurring timer. 

#define INCL DOSDATETIME 
Idefine INCl_DO$$EMAPHORES 

linclude <os2.h> 

Idefine SEMJIAME "\\SEM\\ timer. sen" /* Semaphore name */ 

Idefine TIME_INTERVAL 1000L /* Timer interval (in milliseconds) */ 

main() 

{ 

HSEM SemHandle; 

HTIMER TimerHandle; 

USHORT i ; 

USHORT rc; 

/* Create system semaphore to be used by timers */ 

DosCreateSem(C$EM_PUBLIC, /* Ownership - nonexclusive */ 

&SemHandle, /* Semaphore handle (returned) */ 

SEM_NAME); /* Semaphore name */ 

fit Set the semaphore, then start a one-shot timer */ 
if (IDosSemSet (SemHandle)) fit Semaphore handle itf 

printf( "Semaphore set.\n"); 

i f (! (rc a DosTimerAsync(TIME_INTERVAL, fit Timer interval itf 

SemHandle, fit Semaphore handle itf 

&T i merHandl e) ) ) fit Timer handle (returned) itf 

printf ("One shot timer for %f seconds started. \n\ TIME_INTERVAL/ 1000.0); 

fit Report when timer expires (other work may be done here) itf 
if (IDosSemWait (SemHandle, fit Semaphore handle */ 

SEM_INDEFINITE_WAIT)) fit Timeout period - indefinite itf 
printf ("Time interval has elapsed.\n") ; 

fit Start a recurring timer itf 

if (! (rc=DosTimerStart(TIME_INTERVAL, fit Timer interval itf 

SemHandle, fit Semaphore handle */ 

&Ti merHandl e) ) ) fit Timer handle (returned) itf 

printf ("Recurring timer with %f second interval started. \n" f 
TIMEJNTERVAL/1000.0); 

fit itf 

for(i=I; i <4; i++) 

if(!Dos$emSetWait(SemHandle, fit Semaphore handle itf 

SEM_I NDEFINI TE_WA IT)) fit Timeout period - indefinite */ 
printf ("Recurring timer cleared semaphore %d times. \n", i); 
i f ( ! ( rc s DosTi merStop (T i merHandl e) ) ) fit Timer handle itf 

printf("Recurring timer has been stopped.\n“); 
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DosTimerStop - 
Stop Interval Timer 


This call stops a periodic interval timer started by DosTimerStart, or an asynchronous timer started by 
DosTimerAsync. 


DosTimerStop (Handle) 


Parameters 

Handle ( HTIMER ) - input 

Handle of the timer to be stopped. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

326 ERROR_TS_HANDLE 

Remarks 

DosTimerStop is used to stop an asynchronous one-shot timer started with DosTimerAsync or an asyn- 
chronous periodic interval timer started with DosTimerStart. 

No assumptions can be made about the state of the semaphore specified with DosTimerStart or 
DosTimerAsync. The application should put the semaphores into a known state. 


C Language 

Idefine I NCL_DOSDATET I ME 
USHORT rc = DosTimerStop (Handle) ; 


HTIMER 

Handle; 

/* 

Handle 

of the timer */ 

USHORT 

rc; 

/* 

return 

code */ 


Assembler Language 

EXTRN DosTimerStop: FAR 
INCL_DOSDATETIME EQU 1 

PUSH WORD Handle ;Handle of the timer 

CALL DosTimerStop 

Returns WORD 


Example 

The following example sets an asynchronous one-shot timer for one second. It then sets an asynchro- 
nous recurring timer with a one-second interval, reporting each time an interval elapses. Finally, it stops 
the recurring timer. 


Chapter 2. Control Program Function Calls 


2-385 







DosTimerStop - 
Stop Interval Timer 


#define INCLJJOSDATETIME 
Idefine INCLJJOSSEMAPHORES 

#inc1ude <os2.h> 

#define SEM NAME "WSEMWtimer.sem* 1 /* Semaphore name */ 

#define TIMEJNTERVAL 1G0OL /* Timer Interval (in milliseconds) */ 

main() 

{ 

HSEM SemHandle; 

HTIMER TimerHandle; 

USHORT i ; 

USHORT rc; 

/* Create system semaphore to be used by timers */ 

DosCreateSem(C$EM_PUBLIC, /* Ownership - nonexclusive */ 

SSemHandle, /* Semaphore handle (returned) */ 

SEM_NAME) ; /* Semaphore name */ 

/* Set the semaphore, then start a one-shot timer */ 
if (IDosSemSet (SemHandle)) /* Semaphore handle */ 

pri ntf ( " Semaphore set . \n “ ) ; 

i f ( ! ( rc=DosTi merAsync (TIME_I NTERVAL , /* Timer interval */ 

SemHandle, /* Semaphore handle */ 

&TimerHandle))) /* Timer handle (returned) */ 

pri ntf ("One shot timer for %f seconds started, \n", T I ME_I NTERVAL/ 1000.0); 

/* Report when timer expires (other work may be done here) k/ 
if (IDosSemWait (SemHandle, /* Semaphore handle k/ 

SEM_INDEFINITE_WAIT)) fk Timeout period - indefinite k/ 

printf("Time interval has elapsed. \n") ; 

fk Start a recurring timer kf 

i f ( ! (rc=DosTi merStart (TIME_INTERVAL, fk Timer interval kf 

SemHandle, fk Semaphore handle kf 

&TimerHandle))) fk Timer handle (returned) kf 

pri ntf ("Recurring timer with %f second interval started.\n", 
TIMEJNTERVAL/1000.0); 

fk kf 

f or (i =1 ; i<4; i++) 

if (IDosSemSetWait (SemHandle, fk Semaphore handle kf 

SEMJNDEFINITE_WAIT)) fk Timeout period - indefinite kf 
pri ntf ("Recurring timer cleared semaphore %d times. \n“, i); 
if (! (rc=DosTimerStop(TimerHandle))) fk Timer handle kf 

pri ntf ("Recurring timer has been stopped. \n") ; 

} 
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DosTransactNmPipe - 
Perform Transaction 


This call performs a write followed by a read on a duplex message pipe. 


DosTransactNmPipe (Handle, InBuffer, InBufferLen, OutBuffer, OutBufferLen, BytesOut) 


Parameters 

Handle (HPIPE) - input 

Named pipe handle returned by DosMakeNmPipe or DosOpen. 

InBuffer (PBYTE) - input 

Address of the buffer to write to the pipe. 

InBufferLen ( USHORT) - input 
Number of bytes to be written. 

OutBuffer (PBYTE) - output 

Address of the buffer for returned data. 

OutBufferLen (USHORT) - input 

Maximum size, number of bytes, of returned data. 

BytesOut (PUSHORT) - output 

Address of the number of bytes read. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

11 ERROR_BAD_FORMAT 

230 ERROR_BAD_PIPE 

231 ERROR_PIPE_BUSY 

233 ERROR_PIPE_NOT_CONNECTED 

234 ERROR_MORE_DATA 


Remarks 

DosTransactNmPipe is intended for use only on duplex message pipes. If this call is issued and the pipe 
is not a duplex message pipe, ERROR_BAD_FORMAT is returned. 

This call enables you to implement transaction-oriented dialogs. DosTransactNmPipe writes the entire 
InBuffer to the pipe and then reads a response from the pipe into the OutBuffer. The current state of 
blocking/non-blocking has no effect. DosTransactNmPipe does not return until a message has been read 
into the OutBuffer. If the OutBuffer is too small to contain the response message, ERROR_MORE_DATA is 
returned, as described for DosRead. 


C Language 

Idefine INCLJIOSNMPIPES 

USHORT rc = DosTransactNmPipe (Handle, InBuffer, InBufferLen, OutBuffer, 

OutBufferLen , BytesOut ) ; 


HPIPE 

Handle; 

/* 

PBYTE 

InBuffer; 

/* 

USHORT 

InBufferLen; 

/* 

PBYTE 

OutBuffer; 

/* 

USHORT 

OutBufferLen; 

/* 

PUSHORT 

BytesOut; 

/* 

USHORT 

rc; 

/* 


Pipe handle */ 

Write buffer */ 

Write buffer length */ 
Read buffer (returned) */ 
Read buffer length */ 
Bytes read (returned) */ 

return code */ 
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DosTransactNmPipe - 
Perform Transaction 

Assembler Language 

EXTRN DosTransactNmPipe: FAR 
INCL_DOSNMPIPES EQU 1 

PUSH WORD Handle ; Pi pe handle 

PUSH© OTHER InBuffer ;Write buffer 

PUSH WORD InBufferLen ;Write buffer length 

PUSH© OTHER OutBuffer ;Read buffer (returned) 

PUSH WORD OutBufferLen ;Read buffer length 

PUSH© WORD BytesOut ; Bytes read (returned) 

CALL DosTransactNmPipe 

Returns WORD 
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DosUnlockSeg - 
Unlock Segment 


This call unlocks a discardable segment. 


DosUnlockSeg (Selector) 


Parameters 

Selector (SEL) - input 

Segment selector to be unlocked. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

5 ERROR_ACCESS_DENIED 

158 ERROR JslOTLOCKED 

Remarks 

DosUnlockSeg is called to free memory for possible discard by the system in a low memory situation. 
The memory being freed is originally allocated by a call to DosAllocSeg or DosAllocHuge with AllocFlags 
bit 2 set. This memory may have been reallocated by a call to DosReallocSeg or DosReallocHuge after 
discard by the system. 

Allocation and reallocation calls for discardable memory automatically lock the memory for access by 
the calling process. Thus, to access the segment, the caller does not have to lock the segment with 
DosLockSeg. Once a discardable segment is unlocked by a DosUnlockSeg request, access to the 
segment is gained by a successful DosLockSeg request. 

DosUnlockSeg may also be used on segments that are non~discardable, in which case it has no effect. 

C Language 

f define INCLJOSMEMMGR 

USHORT rc = DosUnlockSeg(Selector) ; 

SEL Selector; /* Selector to unlock */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosUnlockSeg: FAR 
INCL_DOSMEMMGR EQU 1 

PUSH WORD Selector iSelector to unlock 

CALL DosUnlockSeg 

Returns WORD 
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DosWaitNmPipe - 
Wait Named Pipe Instance 


This call waits for the availability of a named pipe instance. 


DosWaitNmPipe (FileName, TimeOut) 


Parameters 

FileName (PSZ) — input 

Address of the ASCIIZ name of the pipe to be opened. Pipes are name \PIPE\FileName. 

TimeOut (ULONG) - input 

Maximum time in milliseconds to wait for the named pipe to become available. When a zero value is 
used, the DosMakeNmPipe specified default value is used. When a minus one value is used, an 
indefinite wait is entered. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

2 ERROR_FILEJMOT_FOUND 

95 ERRORJNTERRUPT 

231 ERROR_PIPE_BUSY 

Remarks 

This call should be used only when ERROR_PIPE_BUSY is returned from a DosOpen call. 

DosWaitNmPipe allows an application to wait for a server on a named pipe for which all instances are 
currently busy. The call waits up to TimeOut milliseconds (or a default time if TimeOut is zero). 

When a pipe instance becomes available, it is given to the process whose thread has the highest priority. 
The priority of a thread may be changed with DosSetPrty. 

C Language 

Idefine INCL_DOSNMPIPES 

USHORT rc = DosWaitNmPipe (FileName, TimeOut); 

PSZ FileName; /* Pipe name */ 

ULONG TimeOut; /* Maximum wait time */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosWa i t NmPi pe : FAR 
INCL_DOSNMPIPES EQU 1 

PUSH® ASCIIZ FileName ;Pipe name 

PUSH DWORD TimeOut ; Maxi mum wait time 

CALL DosWaitNmPipe 

Returns WORD 
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FAPI 


DosWrite - 

Synchronous Write to File 


This call transfers the specified number of bytes from a buffer to the specified file, synchronously with 
respect to the requesting process’s execution. 


DosWrite (FileHandle, BufferArea, BufferLength, BytesWritten) 


Parameters 

FileHandle (HFILE) - input 
File handle from DosOpen. 

BufferArea (PVOID) - input 
Address of the output buffer. 

BufferLength ( USHORT) - input 
Number of bytes to write. 

BytesWritten ( PUSHORT) - output 

Address of the number of bytes written. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

6 ERRORINVALIDJHANDLE 

26 ERROR_NOT_DOS_DISK 

33 ERROR_LOCK_VIOLATION 

109 ERROR_BROKEN_PIPE 

Remarks 

On output, BytesWritten is the number of bytes actually written. If BytesWritten is different from 
BufferLength, this usually indicates insufficient disk space. 

A BufferLength value of 0 is not considered an error. No data transfer occurs. There is no effect on the 
file or the file pointer. 

Buffers that are multiples of the hardware’s base physical unit for data written to the file on these base 
boundaries, are written directly to the device. (The base physical unit is defined as the smallest block 
that can be physically written to the device.) Other buffer sizes force some I/O to go through an internal 
system buffer and greatly reduce the efficiency of I/O operation. 

The file pointer is moved by read and write operations. It can be moved to a desired position by calling 
DosChgFilePtr. 

If the file is read-only, the write to the file is not performed. 

Family API Considerations 

Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction 
applies to DosWrite when coding for the DOS mode. 

• Only single-byte DosWrite requests can be made to the COM device, because the COM device driver 
for the DOS environment does not support multiple-byte I/O. 
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DosWrite - 

Synchronous Write to File 


FAPI 


Named Pipe Considerations 

DosWrite Is also used to write bytes or messages to a named pipe. 

Each write to a message pipe writes a message whose size is the length of the write; DosWrite automat- 
ically encodes message lengths in the pipe, so applications need not encode this information in the buffer 
being written. 

Writes in blocking mode always write all requested bytes before returning. In non-blocking mode, if the 
message size is bigger than the buffer size, the write blocks. If the message size is smaller than the pipe 
but not enough space is left in the pipe, the write returns immediately with a value of zero, indicating no 
bytes were written. 

In the case of a byte pipe, if the number of bytes to be written exceeds the space available in the pipe, 
DosWrite writes as many bytes as it can and returns with the number of bytes actually written. 

An attempt to write to a pipe whose other end has been closed returns ERROR_BROKEN__PIPE. 

C Language 

#defi ne INCL_DOSFILEMGR 

USHORT rc = DosWrite (FileHandle, BufferArea, BufferLength, BytesWritten) ; 

HFILE FileHandle; /* File handle */ 

PVOID BufferArea; /* User buffer */ 

USHORT BufferLength; /* Buffer length */ 

PUSHORT BytesWritten; /* Bytes written (returned) */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosWrite; FAR 
INCLJIOSFILEMGR EQU 1 

PUSH WORD FileHandle ; Fi 1 e handle 

PUSH@ OTHER BufferArea ;User buffer 

PUSH WORD BufferLength ; Buffer length 

PUSH@ WORD BytesWritten ; Bytes written (returned) 

CALL DosWrite 

Returns WORD 
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fapi DosWrite - 

Synchronous Write to File 


Example 

This example writes to a file. 

#de fine INCLJ50SFILEMGR 

#de fine OPEN FILE GxOl 
#define CREATE FILE 0x10 
#define FILE_ARCHIVE 0x20 
Idefine FILE_EXISTS OPEN.FILE 
Idefine FILE NOEXISTS CREATE_FILE 
Idefine DASd‘fu\G 0 
Idefine INHERIT 0x80 
Idefine WRITE_THRU 0 
Idefine FAIL_FLAG 0 
Idefine SHARE FUG 0x10 
Idefine ACCESS JUG 0x02 

Idefine FILE NAME "test.dat" 

Idefine FILE_SIZE 800L 

Idefine FILE.ATTRIBUTE F I LE_ARCH I VE 

Idefine RESERVED 0L 

HFILE FileHandle; 

USH0RT Wrote; 

USH0RT Action; 

PSZ F11eData[lG0] ; 

USHORT rc; 

Action = 2; 

strcpy(FileData, "Data..."); 

if(!DosOpen(FILE_NAME, /* File path name */ 

&Fi1eHand1e, /* File handle */ 

&Action, /* Action taken */ 

FILE SIZE, /* File primary allocation */ 

FILEJTTRIBUTE, /* File attribute */ 

FI LE_EXI STS ! FILE_NOEXISTS, /* Open function type */ 

DASD FUG | INHERIT [ /* Open mode of the file */ 

WRITE_THRU | FAIL JUG | 

SHARE_FUG | ACCESS_FUG, 

RESERVED)) /* Reserved (must be zero) */ 

rc - DosWrite(FileHandle, /* File handle */ 

(PVOID) FileData, /* User buffer */ 

sizeof (FileData) , /* Buffer length */ 

&Wrote); /* Bytes written */ 
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DosWriteAsync - 
Asynchronous Write to File 


This call asynchronously transfers the specified number of bytes from a buffer to a file, from a buffer. 


DosWriteAsync (FileHandle, RamSemaphore, ReturnCode, BufferArea, BufferLength, 
BytesWritten) 


Parameters 

FileHandle ( HFILE ) - input 

File handle obtained from DosOpen. 

RamSemaphore ( PULONG ) - input 

Address used by the system to signal the caller that the write operation is complete. 

ReturnCode ( PUSHORT) - output 

Address of the I/O error return code. 

BufferArea (PVOID) - input 
Address of the output buffer. 

BufferLength ( USHORT) - input 
Number of bytes to be written. 

BytesWritten (PUSHORT) - output 

Address of the number of bytes written. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

5 ERROR_ACCESS_DENIED 

6 ERRORJNVALIDJHANDLE 

26 ERROR_NOT_DOSJDISK 

33 ERROR_LOCK_VIOLATION 

89 ERROR_NO_PROC_SLOTS 

109 ERROR_BROKEN_PIPE 

Remarks 

A BufferLength value of 0 is not considered an error. No data transfer occurs. There is no effect on the 
file or the file pointer. 

A call to DosWriteAsync may return before the write is complete. To wait for the asynchronous write to 
complete, RamSemaphore must be set by the application before the DosWriteAsync call is made. The 
application issues DosSemSet to set the semaphore, calls DosWriteAsync, and then issues DosSemWait 
to wait for the clearing of the semaphore, which signals the write is complete. 

When RamSemaphore is cleared, BytesWritten identifies the number of bytes written. If BytesWritten is 
different from BufferLength, it usually indicates insufficient disk space. 

The program must not modify the contents of BufferArea or look at the values returned in ReturnCode or 
BytesWritten until after RamSemaphore is cleared. 

Buffers that are multiples in size of the hardware's base physical unit for data, written to the file on these 
base boundaries, are written directly to the device. (The base physical unit is defined as the smallest 
block that can be physically written to the device.) Other buffer sizes force at least some I/O to go 
through an internal system buffer (if the file handle state bit indicates that internal buffers may be used) 
and reduce the efficiency of I/O operation. 
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DosWriteAsync - 
Asynchronous Write to File 


The read/write pointer is moved by I/O operations. It can also be moved to a desired position by calling 
DosChgFilePtr. The value of the pointer is updated by the File Level Request Router before the I/O 
request is queued to the device driver. 

If the file is read-only, the write to the file is not performed. 

Note: If it is necessary to make a DosWriteAsync request from within a segment that has I/O privilege, 
DosCallback may be used to invoke a privilege level 3 segment, which makes the actual 
DosWriteAsync request. 

Named Pipe Considerations 

DosWriteAsync is also used to write bytes and messages to named pipes. 

Each write to a message pipe writes a message whose size is the length of the write; DosWriteAsync 
automatically encodes message lengths in the pipe, so applications need not encode this information in 
the buffer being written. 

Writes in blocking mode always write all requested bytes before returning. In non-blocking mode, if the 
message size is bigger than the buffer size, the write blocks. If the message size is smaller than the 
pipe, but not enough space is left in the pipe, DosWriteAsync returns immediately with a value of zero, 
indicating no bytes were written. 

In the case of a byte pipe, if the number of bytes to be written exceeds the space available in the pipe, 
DosWriteAsync writes as many bytes as it can and returns with the number of bytes actually written. 

An attempt to write to a pipe whose other end has been closed returns with ERROR_BROKEN_PIPE. 

C Language 

#define INCL_DOSFILEMGR 

USKORT rc ** DosWriteAsync(Fi leHandle, RamSemaphore, ReturnCode, 

BufferArea, BufferLength, BytesWritten); 


HFILE 

Fi leHandle; 

/* File handle */ 

PULONG 

RamSemaphore 

; /* RAM semaphore */ 

PUSHORT 

ReturnCode; 

lie I/O operation return code (returned) */ 

PVOID 

BufferArea; 

lie User buffer */ 

USHORT 

BufferLength 

; /ie Buffer length */ 

PUSHORT 

BytesWritten; /* Bytes written (returned) */ 

USHORT 

rc; 

lie return code */ 

Assembler Language 

EXTRN DosWri teAsync: FAR 

INCLJJOSFILEMGR EQU 1 

PUSH WORD 

Fi leHandle 

;File handle 

PUSH® DWORD 

RamSemaphore 

;Ram semaphore 

PUSH® WORD 

ReturnCode 

; I/O operation return code (returned) 

PUSH® OTHER 

BufferArea 

;User buffer 

PUSH WORD 

BufferLength 

; Buffer length 

PUSH® WORD 

BytesWri tten 

; Bytes written (returned) 


CALL DosWri teAsync 


Returns WORD 
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DosWriteQueue - 
Write to Queue 


This call adds an element to a queue. 


DosWriteQueue (QueueHandle, Request, DataLength, DataBuffer, ElemPriorlty) 


Parameters 

QueueHandle {HQUEUE) - input 
Queue handle. 

Request ( USHORT) - input 

A value to be passed with the queue element. This word is used for event encoding by the specific 
application. 

DataLength {USHORT) - input 

Length of the data being sent to the queue. 

DataBuffer {PBYTE) - input 

Address of the data buffer where data t that is to be placed in the queue, is located. 

ElemPriorlty {UCHAR) - input 

Priority of the element being added to the queue. If the priority is specified as 15, the element is 
added to the top of the queue (that is, in LIFO order). If the priority is specified as 0, the element is 
added as the last element in the queue (that is, in FIFO order). Elements with the same priority are 
in FIFO order. This parameter is valid for priority-type queues only. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

334 ERROR_QUE_NO_M EMORY 

337 ERROR_QUE_INVALID_HANDLE 

Remarks 

DosWriteQueue adds entries to a specified queue. 

The Request, DataLength and DataBuffer parameters contain data understood by the thread adding the 
element to the queue and by the thread that receives the queue element. There is no special meaning to 
this data; applications may use these parameters for any purpose they wish. OS/2 does not alter this 
data; it simply copies this data intact. OS/2 does not validate the address of DataBuffer or the 
DataLength. 

If the queue owner has defined a semaphore for use in its notification when elements are added to the 
queue and if that semaphore is a RAM semaphore, then that semaphore must be in a segment which is 
shared among both the queue owner's process and this process. If that semaphore handle is for a 
system semaphore, then that semaphore must be opened by this process before making a 
DosWriteQueue request to the queue. 

If the owning process is terminated, or if the queue is closed before this request is issued, 
ERROR_QUE_INVALID_HANDLE is returned. 

If the owning process invokes a system semaphore when DosReadQueue or DosPeekQueue is issued, 
other processes that issue DosWriteQueue must first issue DosOpenSem to access the system 
semaphore. 
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DosWriteQueue - 
Write to Queue 

C Language 

f define INCL_00SQUEUES 

USHORT rc = DosWriteQueue (QueueHandle, Request, DataLength, DataBuffer, 

ElemPriority); 

HQUEUE QueueHandle; /* Queue handle */ 

USHORT Request; /* Request identification data */ 

USHORT DataLength; /* Length of element being added */ 

PBYTE DataBuffer; /* Element being added */ 

UCHAR ElemPriority; /* Priority of element being added */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN DosWriteQueue: FAR 
INCLJJOSQUEUES EQU 1 

PUSH WORD QueueHandle ; Queue handle 

PUSH WORD Request ; Request identification data 

PUSH WORD DataLength ; Length of element being added 

PUSH© OTHER DataBuffer ; Element being added 

PUSH WORD ElemPriority priority of element being added 

CALL DosWri teQueue 

Returns WORD 
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Chapter 3. Keyboard Function Calls 

This chapter reflects the Keyboard API interface of OS/2 only. 

For information regarding the keyboard IOCTL interface and keyboard monitor refer to IBM Operating 
System/2 Version 1.2 I/O Subsystems And Device Support Volume 1. 

Notes: 

1. Calls marked xPM are not supported by Presentation Manager, and must not be used by Presenta- 
tion Manager applications. An error code is returned if any of these calls are issued. 

2. Calls marked xWPM are not windowable and are not supported by Presentation Manager. They can 
be used in OS/2 mode. 

3. Calls marked FAPI are present in the Family API. 

4. Those calls without an icon are: 

• Windowable 

• Presentation Manager 

• Full-screen 

• Not Family API. 
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KbdCharln - 

Read Character, Scan Code 


FAP! xPM 


This call returns a character data record from the keyboard. 


KbdCharln (CharData, lOWait, KbdHandle) 


Parameters 

CharData ( PKBDKEYINFO ) - output 

Address of the character data structure: 

asciicharcode ( UCHAR ) 

ASCII character code. The scan code received from the keyboard is translated to the ASCII 
character code. 

scancode (UCHAR) 

Code received from the keyboard. The scan code received from the keyboard is translated to 
the ASCII character code. 

status (UCHAR) 

State of the keystroke event: 

Bit Description 

7-6 00 = Undefined 

01 = Final character, interim character flag off 

10 = Interim character 

11 = Final character, interim character flag on. 

5 1 = Immediate conversion requested. 

4-2 Reserved. 

1 0 = Scan code is a character. 

1 = Scan code is not a character; is an extended key code from the keyboard. 

0 1 = Shift status returned without character, 
reserved (UCHAR) 

NLS shift status. Reserved, set to zero. 

shlftkeystat (USHORT) 

Shift key status. 

Bit Description 

15 SysReq key down 

14 CapsLock key down 

13 NumLock key down 

12 ScrollLock key down 

1 1 Right Alt key down 

10 Right Ctrl key down 

9 Left Alt key down 

8 Left Ctrl key down 

7 Insert on 

6 CapsLock on 

5 NumLock on 

4 ScrollLock on 

3 Either Alt key down 

2 Either Ctrl key down 

1 Left Shift key down 

0 Right Shift key down 
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fapi xpm KbdCharln - 

Read Character, Scan Code 


time (ULONG) 

Time stamp indicating when a key was pressed. It is specified in milliseconds from the time the 
system was started. 

lOWait (USHORT) - input 

Wait if a character is not available. 

Value Definition 

0 Requestor waits for a character if one is not available. 

1 Requestor gets an immediate return if no character is available. 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

375 ERROR_KBD_INVALIDJOWAIT 

439 ERROR_KBD_INVALID_HANDLE 

445 ERROR_KBD_FOCUS_REQUIRED 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

On an enhanced keyboard, the secondary enter key returns the normal character ODH and a scan code of 
EOH. 

Double-byte character codes (DBCS) require two function calls to obtain the entire code. 

If shift report is set with KbdSetStatus, the CharData record returned reflects changed shift information 
only. 

Extended ASCII codes are identified with the status byte, bit 1 on and the ASCII character code being 
either 00H or EOH. Both conditions must be satisfied for the character to be an extended keystroke. For 
extended ASCII codes, the scan code byte returned is the second code (extended code). Usually the 
extended ASCII code is the scan code of the primary key that was pressed. 

A thread in the foreground session that repeatedly polls the keyboard with KbdCharln (with no wait), can 
prevent all regular priority class threads from executing. If polling must be used and a minimal amount 
of other processing is being performed, the thread should periodically yield to the CPU by issuing a 
DosSleep call for an interval of at least 5 milliseconds. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to KbdCharln when coding in the DOS mode: 

• The CharData structure includes everything except the time stamp. 

• Interim character is not supported 

• Status can be 0 or 40H 

• KbdHandle is ignored. 
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KbdCharln - 

Read Character, Scan Code 


FAPI xPM 


C Language 


typedef struct .KBDKEYINFO { 

/* kbci */ 

UCHAR 

chChar; 

/* ASCII character code */ 

UCHAR 

chScan; 

/* Scan Code */ 

UCHAR 

fbStatus; 

/* State of the character */ 

UCHAR 

bNlsShift; 

/* Reserved (set to zero) */ 

USHORT 

fsState; 

/* State of the shift keys */ 

ULONG 

time; 

/* Time stamp of keystroke (ms since ipl) */ 


}KBDKEYINFO; 

Jdefine INCLJCBO 

USHORT rc = KbdCharln (CharData, IOWait, KbdHandle); 

PKBOKEYINFO CharData; /* Buffer for data */ 

USHORT IOWait; /* Indicate if wait */ 

HKBD KbdHandle; /* Keyboard handle */ 

USHORT rc; /* return code */ 

Assembler Language 

KBDKEYINFO struc 

kbci_chChar db ? ; ASCI I character code 
kbci_chScan db ? ;Scan Code 
kbci_fbStatus db ? ; State of the character 
kbci_bNls$hift db ? ; Reserved (set to zero) 
kbci_fsState dw ? ; state of the shift keys 
kbci time dd ? ;time stamp of keystroke (ms since ipl) 
KBDKEYINFO ends 

EXTRN KbdCharln: FAR 
INCLJCBO EQU 1 

PUSH@ OTHER CharData ; Buffer for data 

PUSH WORD IOWait indicate if wait 

PUSH WORD KbdHandle keyboard handle 

CALL KbdCharln 

Returns WORD 
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xpm KbdClose - 

Close a Logical Keyboard 


This call closes the existing logical keyboard identified by the keyboard handle. 


KbdClose (KbdHandle) 


Parameters 

KbdHandle ( HKBD ) - input 

Default keyboard or the logical keyboard. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

439 ERROR_KBD_INVALID_HANDLE 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 


Remarks 

KbdClose blocks while another thread has the keyboard focus (by way of KbdGetFocus) until the thread 
with the focus issues KbdFreeFocus. Therefore, to prevent KbdClose from blocking, it is recommended 
that KbdClose be issued only while the current thread has the focus. For example: 


KbdGetFocus 

KbdClose 

KbdClose 

KbdClose 

KbdFreeFocus 


Wait until focus available on handle 0. 
Close a logical keyboard handle. 

Close another logical keyboard handle. 
Close still another logical keyboard handle. 
Give up the focus on handle 0. 


C Language 

Idefine INCL_KBD 

USHORT rc » KbdClose(KbdHandle) ; 


HKBD 

KbdHandle; 

/* Keyboard handle */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN KbdClose: FAR 
INCL_KBD EQU 1 

PUSH WORD KbdHandle keyboard handle 
CALL KbdClose 

Returns WORD 
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KbdDeRegister - 
Deregister Keyboard Subsystem 


xWPM 


This call deregisters a keyboard subsystem previously registered within a session. Only the process that 
issued the KbdRegister may issue KbdDeRegister. 


KbdDeRegister ( ) 


Parameters 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

411 ERROR_KBD_DEREGISTER 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

C Language 

#define INCL_KBD 

USHORT rc = KbdDeRegister (VOID) ; 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN KbdDeRegister: FAR 
INCL_KBD EQU 1 

CALL KbdDeRegister 

Returns WORD 
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FAPI xPM 


KbdFlushBuffer - 
Flush Keystroke Buffer 


This call clears the keystroke buffer. 


KbdFlushBuffer (KbdHandle) 


Parameters 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

439 ERROR_KBDJNVAUD_HANDLE 

445 ERROR_KBD_FOCUS_REQUIRED 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

KbdFlushBuffer completes when the handle has access to the physical keyboard (focus), or Is equal to 
zero and no other handle has the focus. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. The KbdHandle is ignored 
when coding in the DOS mode. 


C Language 

Idefine INCL.KBD 

USHORT rc » KbdFlushBuffer(KbdHandle) ; 


HKBD 

KbdHandle; 

/* Keyboard handle 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN KbdFlushBuffer: FAR 
INCLJCBD EQU 1 

PUSH WORD KbdHandle ; Keyboard handle 
CALL KbdFlushBuffer 

Returns WORD 
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KbdFreeFocus - 
Free Keyboard Focus 


xPM 


This call frees the logical-to-physical keyboard bond created by KbdGetFocus. 


KbdFreeFocus (KbdHandle) 


Parameters 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

439 ERROR_KBDJNVALID_HANDLE 

445 ERROR_KBD_FOCUS_REQUIRED 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

KbdFreeFocus may be replaced by issuing KbdRegister. Unlike other keyboard subsystem functions, the 
replaced KbdFreeFocus is called only if there is an outstanding focus. 


C Language 

f define INCL_KBD 

USHORT rc - KbdFreeFocus (KbdHandl e) ; 


HKBD 

KbdHandle; 

/* Keyboard handle */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN KbdFreeFocus: FAR 
INCL_KBD EQU 1 

PUSH WORD KbdHandle ; Keyboard handle 
CALL KbdFreeFocus 

Returns WORD 


3-8 


Control Program Programming Reference 







KbdGetCp - 
Get Loaded Code Page ID 


This call allows a process to query the code page being used to translate scan codes to ASCII characters. 


KbdGetCp (Reserved, CodePagelD, KbdHandle) 

Parameters 

Reserved (ULONG) - input 

Reserved and must be set to zero. 

CodePagelD (PUSHORT) - output 

Address of the code page ID located in the application’s data area. The keyboard support copies the 
current code page ID for a specified keyboard handle into this word. The code page ID is equivalent 
to one of the code page IDs specified in the CONFIG.SYS CODEPAGE = statement or 0000. 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

re ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

373 ERROR_KBD_PARAMETER 

439 ERRORJ<BDJNVALID_HANDLE 

445 ERROR_KBD_FOCUS_REQUIRED 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

The CodePagelD is the currently active keyboard code page. A value of 0 indicates the code page trans- 
lation table in use is the ROM code page translation table provided by the hardware. 

C Language 

Idefine INCL_KBD 

USHORT re = KbdGetCp(Reserved. CodePagelD, KbdHandle); 

ULONG Reserved; /* Reserved (must be zero) */ 

PUSHORT CodePagelD; /* Code Page ID */ 

HKBD KbdHandle; /* Keyboard handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN KbdGetCp; FAR 

INCLJCBD EQU 1 

PUSH DWORD Reserved ; Reserved (must be zero) 

PUSH0 WORD CodePagelD ;Code Page ID 

PUSH WORD KbdHandle keyboard handle 

CALL KbdGetCp 

Returns WORD 


Chapter 3. Keyboard Function Calls 3-9 







KbdGetFocus - 
Get Keyboard Focus 


xPM 


This call binds the logical keyboard to the physical keyboard. 


KbdGetFocus (IOWait, KbdHandle) 

Parameters 

lOWait ( USHORT) - input 

Wait if the physical keyboard is already in use by a logical keyboard. 

Value Definition 

0 Indicates that the caller wants to wait for the bond. 

1 Indicates that the caller does not want to wait for the bond. 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

439 ERROR_KBD_INVALID_HANDLE 

446 ERROR J<BDJ=OCUS_ALREADY_ACTIVE 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR_KBDJDETACHED 

504 ERROR_KDB_EXTENDED_SG 

The keyboard handle identifies which logical keyboard to bind to. If the physical keyboard is not bound to 
a logical or default keyboard, then the bind proceeds immediately. The logical keyboard, identified by the 
handle, receives all further key strokes from the physical keyboard. If the physical keyboard is already in 
use by a logical keyboard, then the thread issuing KbdGetFocus waits until the bond can be made. 

Waiting threads do not execute in any definable order. 

C Language 

Idefine INCL_KBD 

USHORT rc = KbdGetFocus (IOWait, KbdHandle); 

USHORT IOWait; /* Indicate if wait */ 

HKBO KbdHandle; /* Keyboard handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN KbdGetFocus: FAR 
INCL_K0D EQU 1 

PUSH WORD IOWait : Indicate if wait 

PUSH WORD KbdHandle ; Keyboard handle 

CALL KbdGetFocus 

Returns WORD 
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KbdGetHWId - 
Query Keyboard Hardware ID 


Returns the attached keyboard's hardware-generated Identification value. 


KbdGetHWId (KeyboardID, KbdHandle) 


Parameters 

KeyboardID (PKBDHWID) - input 

Pointer to the caller’s data area where the following structure and data values are: 
length ( USHORT) — input/output 

On input, this field should contain the length of the KeyboardID structure. The minimum input 
length value allowed is 2. On output, this field contains the actual number of bytes returned. 

keybdid (USHORT) - output 

OS/2 supported keyboards and their hardware generated IDs are as follows: 


ID 

Keyboard 

0000H 

Undetermined keyboard type 

0001 H 

PC-AT Standard Keyboard 

AB41H 

101 Key Enhanced Keyboard 

AB41H 

102 Key Enhanced Keyboard 

AB54H 

88 and 89 Key Enhanced Keyboards 

AB85H 

122 Key Enhanced Keyboard 


reserved ( USHORT) 

Reserved and returned set to zero. 

reserved ( USHORT) 

Reserved and returned set to zero. 

KbdHandle (HKBD) - input 

Word identifying the logical keyboard. 

rc (USHORT) - return 

Return code descriptions are: 

373 ERROR_KBD_PARAMETER 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

In past OS/2 releases, all keyboards could be supported by knowing the hardware family information 
available with keyboard IOCTL 77H. However, with the addition of the 122-key keyboard, recognition was 
not containable by hardware family information alone. The 122-key keyboard has a number of differ- 
ences from other keyboards. Therefore, applications performing keystroke specific functions may need 
to determine specifically which keyboard is attached. 

This function is of particular usefulness for applications providing Custom Translate Tables and mapping 
keyboard layouts. 
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KbdGetHWId - 

Query Keyboard Hardware ID 


C Language 

typedef struct _KBDHWID { 

USHORT length; /* length in bytes of this structure */ 

USHORT kbd_id; /* attached keyboard's hardware ID (returned) */ 

USHORT reservedl; /* reserved (set to zero) */ 

USHORT reserved2; /* reserved (set to zero) */ 

}KBDHWID; 

Idefine INCL.KBD 

USHORT rc = KbdGetHWId (KeyboardID, KbdHandle); 

PKBDHWID KeyboardID; /* Keyboard ID structure (returned) */ 

HKBD KbdHandle; /* Keyboard handle */ 

USHORT rc; /* return code */ 


Assembler Language 

KBDHWID struc 
length; 
kbdjd; 
reservedl; 
reserved2; 

KBDHWID ends 

EXTRN KbdGetHWId: FAR 
INCL.KBD EQU 1 

PUSH? OTHER KeyboardID ; Keyboard ID structure (returned) 

PUSH WORD KbdHandle keyboard handle 

CALL KbdGetHWId 

Returns WORD 


dw ? ; length in bytes of this structure 
dw ? ; attached keyboard's hardware ID (returned) 
dw ? ; reserved (set to zero) 
dw ? reserved (set to zero) 
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FAPI xPM 


KbdGetStatus - 
Get Keyboard Status 


This call gets the current state of the keyboard. 


KbdGetStatus (StatData, KbdHandle) 


Parameters 

StatData ( PKBDINFO ) - output 

Address of the keyboard status structure: 

length (USHORT) 

Length, in bytes, of this data structure, including length. 

10 Only valid value. 

sysstate ( USHORT) 

State as follows: 

Bit Description 

15-9 Reserved, set to zero. 

8 Shift return is on. 

7 Length of the turn-around character (meaningful only if bit 6 is on). 

6 Turn-around character is modified. 

5 Interim character flags are modified. 

4 Shift state is modified. 

3 ASCII mode is on. 

2 Binary mode is on. 

1 Echo off. 

0 Echo on. 

turnchardef ( USHORT) 

Definition of the turn-around character. In ASCII and extended-ASCII format, the turn-around 
character is defined as the carriage return. In ASCII format only, the turn-around character is 
defined in the low-order byte. 

intcharflag ( USHORT) 

Interim character flags: 

Bit Description 

15-8 NLS shift state. 

7 Interim character flag is on. 

6 Reserved, set to zero. 

5 Application requested immediate conversion. 

4-0 Reserved, set to zero. 

shiftstate (USHORT) 

Shift state as follows: 

Bit Description 

15 SysReq key down 

14 CapsLock key down 

13 NumLock key down 

12 Scroll Lock key down 

11 Right Alt key down 

10 Right Ctrl key down 

9 Left Alt key down 

8 Left Ctrl key down 

7 Insert on 

6 CapsLock on 

5 NumLock on 

4 ScrollLock on 
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KbdGetStatus - 
Get Keyboard Status 


FAPI xPM 


3 Either Alt key down 

2 Either Ctrl key down 

1 Left Shift key down 

0 Right Shift key down. 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

376 ERROR_KBDJNVALID_LENGTH 

439 ERROR_KBDJNVALID_HANDLE 

445 ERRORJ<BD_FOCUS_REQUIRED 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR _KBD_DETACHED “ 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

The initial state of the keyboard is established by the system at application load time. Some default 
states may be modified by the application through KbdSetStatus. KbdGetStatus returns only those key- 
board parameters initially set by KbdSetStatus. The returned parameters are: 

• Input Mode 

• Interim Character Flags 

• Shift State 

• Echo State 

• Turnaround Character 

KbdGetStatus completes only when the handle has access to the physical keyboard (focus) or the handle 
is 0 and no other handle has the focus. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to KbdGetStatus when coding in the DOS mode: 

• Interim character is not supported 

• TurnAround character is not supported 

• NLS_SHIFT_STATE is always NULL. 

• KbdHandle is ignored. 

C Language 

typedef struct KBDINFO { 

USHORT cb; 

USHORT fsMask; 

USHORT chTurnAround; 

USHORT fs Interim; 

USHORT fsState; 

}KBDINF0; 


Idefine INCLJCBD 

USHORT rc = KbdGetStatus (Structure, KbdHandle); 


PKBDINFO 

Structure; 

/* Data structure */ 

HKBD 

KbdHandle; 

/* Keyboard handle */ 

USHORT 

rc; 

/* return code */ 


/* kbst */ 

/* length in bytes of this structure */ 
/* bit mask of functions to be altered */ 
/* define TurnAround character */ 

/* interim character flags */ 

/* shift states */ 
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FAPI xPM 


KbdGetStatus - 
Get Keyboard Status 


Assembler Language 

KBDINFO struc 
kbst_cb dw 

kbst_fsMask dw 

kbst_chTurnAround dw 
kbst_fslnteriin dw 

kbst_fs$tate dw 

KBDINFO ends 

EXTRN KbdGetStatus: FAR 
INCLJ<BD EQU 1 

PUSH© OTHER Structure ;Data structure 

PUSH WORD KbdHandle ; Keyboard handle 

CALL KbdGetStatus 

Returns WORD 


? ; length in bytes of this structure 
? ;bit mask of functions to be altered 
? ; define TurnAround character 
? ; interim character flags 
? ; shift states 
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KbdOpen - 

Open a Logical Keyboard 


xPM 


This call creates a new logical keyboard. 


KbdOpen (KbdHandle) 


Parameters 

KbdHandle ( PHKBD ) - output 

Address of the logical keyboard. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

440 ERROR_KBD_NO_MOREJHANDLE 

441 ERROR_KBD_CANNOT_CREATE_KCB 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 


Remarks 

KbdOpen blocks while another thread has the keyboard focus (by way of KbdGetFocus) until the thread 
with the focus issues KbdFreeFocus. Therefore, to prevent KbdOpen from blocking, it is recommended 
that KbdOpen be issued only while the current thread has the focus. For example: 


KbdGetFocus 

KbdOpen 

KbdOpen 

KbdOpen 

KbdFreeFocus 


wait until focus available on handle 0 
get a logical keyboard handle 
get another logical keyboard handle 
get yet another logical keyboard handle 
give up the focus on handle 0. 


C Language 

#define INCL_KBD 

USHORT rc = KbdOpen (KbdHandle); 


PHKBD 

KbdHandle; 

/* Keyboard handle */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN KbdOpen: FAR 
1NCL_KBD EQU 1 

PUSH© WORD KbdHandle ; Keyboard handle 
CALL KbdOpen 

Returns WORD 
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fapi xpm KbdPeek - 

Peek at Character, Scan Code 

This call returns any available character data record from the keyboard without removing it from the 
buffer. 


KbdPeek (CharData, KbdHandle) 

Parameters 

CharData ( PKBDKEYINFO ) - output 

Address of the character data information: 

asciicharcode (UCHAR) 

ASCII character code. The scan code received from the keyboard is translated to the ASCII 
character code. 

scancode (UCHAR) 

Code received from the keyboard hardware. 

status (UCHAR) 

State of the keystroke event: 

Bit Description 

7-6 00 = Undefined. 

01 = Final character, interim character flag off. 

10 = Interim character. 

11 = Final character, interim character flag on. 

5 1 = Immediate conversion requested. 

4-2 Reserved, set to zero. 

1 0 = Scan code is a character. 

1 = Scan code is not a character; it is an extended key code from the keyboard. 

0 1 = Shift status returned without character, 

reserved (UCHAR) 

NLS shift status. Reserved, set to zero. 

shiftkeystat (USHORT) 

Shift key status. 

Bit Description 

15 SysReq key down 

14 CapsLock key down 

13 NumLock key down 

12 ScrollLock key down 

11 Right Alt key down 

10 Right Ctrl key down 

9 Left Alt key down 

8 Left Ctrl key down 

7 Insert on 

6 CapsLock on 

5 NumLock on 

4 ScrollLock on 

3 Either Alt key down 

2 Either Ctrl key down 

1 Left Shift key down 

0 Right Shift key down 
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KbdPeek - 

Peek at Character, Scan Code 


FAPI xPM 


time (ULONG) 

Time stamp indicating when a key was pressed. It is specified in milliseconds from the time the 
system was started. 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

439 ERROR_KBDJNVALID_HANDLE 

445 ERROR_KBD_FOCUS_REQUIRED 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

On an enhanced keyboard, the secondary enter key returns the normal character ODH and a scan code of 
EOH. 

Double-byte character codes (DBCS) require two function calls to obtain the entire code. 

If shift report is set with KbdSetStatus the CharData record returned, reflects changed shift information 
only. 

Extended ASCII codes are identified with the status byte, bit 1 on and the ASCII character code being 
either 00H or EOH. Both conditions must be satisfied for the character to be an extended keystroke. For 
extended ASCII codes, the scan code byte returned is the second code (extended code). Usually the 
extended ASCII code is the scan code of the primary key that was pressed. 

A thread in the foreground session that repeatedly polls the keyboard with KbdCharln (with no wait), can 
prevent all regular priority class threads from executing. If polling must be used and a minimal amount 
of other processing is being performed, the thread should periodically yield the CPU by issuing a 
DosSleep call for an interval of at least 5 milliseconds. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to KbdPeek when coding for the DOS mode: 

• The CharData structure includes everything except the time stamp. 

• Interim character is not supported. 

• Status can be 0 or 1 . 

• KbdHandle is ignored. 

C Language 


typedef struct _KBDKEYINF0 { 

/* kbci */ 

UCHAR 

chChar; 

/* ASCII character code */ 

UCHAR 

chScan; 

/* Scan Code */ 

UCHAR 

fbStatus; 

/* State of the character */ 

UCHAR 

bNlsShift; 

/it Reserved (set to zero) */ 

USHORT 

fsState; 

/* State of the shift keys it/ 

ULONG 

time; 

/it Time stamp of keystroke (ms since ipl) it/ 

JKBDKEYINFO; 


#define 

INCLJCBD 


USHORT 

rc = KbdPeek (CharData, 

KbdHandle) ; 

PKBDKEYINFO CharData; 

/it Buffer for data */ 

HKBD 

KbdHandle; 

/it Keyboard handle it/ 

USHORT 

rc; 

/it return code */ 
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fapi xpm KbdPeek - 

Peek at Character, Scan Code 

Assembler Language 

KBOKEYINFO struc 

kbci_chChar db ? ; ASCI I character code 

kbcijrhScan db ? ;Scan Code 

kbci_fbStatus db ? ; State of the character 

kbciJbNlsShift db ? Reserved (set to zero) 

kbci_fsState dw ? ;state of the shift keys 

kbci_time dd ? ;time stamp of keystroke (ms since ipl) 

KBDKEYINFO ends 

EXTRN KbdPeek: FAR 
INCL_KBD EQU 1 

PUSm OTHER CharData ; Buffer for data 

PUSH WORD KbdHandl e ; Keyboard handle 
CALL KbdPeek 

Returns WORD 
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Kbd Register - 

Register Keyboard Subsystem 


xWPM 


This call registers a keyboard subsystem within a session. 


KbdRegister (ModuleName, EntryPoint, FunctionMask) 


Parameters 

ModuleName (PSZ) - input 

Address of the dynamic link module name. Maximum length is 9 bytes (including ASCIIZ terminator). 
EntryPoint (PSZ) - input 

Address of the dynamic link entry point name of a routine that receives control when any of the regis- 
tered functions are called. Maximum length is 33 bytes (including ASCIIZ terminator). 

FunctionMask (ULONG) - input 

A bit mask where each bit identifies a keyboard function being registered. The bit values are: 

Bit Description 

31-15 Reserved, must be set to zero. 

14 KbdGetHWId 

13 KbdSetCustXt 

12 KbdXlate 

11 KbdSetCp 

10 KbdGetCp 

9 KbdFreeFocus 

8 KbdGetFocus 

7 KbdClose 

6 KbdOpen 

5 KbdStringln 

4 KbdSetStatus 

3 KbdGetStatus 

2 KbdFlush Buffer 

1 KbdPeek 

0 KbdCharln 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

408 ERROR_KBD_INVALID_ASCIIZ 

409 ERROR_KBDJNVALID_MASK 

41 0 ERROR _KBD_REGISTER 

464 ERROR_KBD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

There can be only one KbdRegister call outstanding for each session without an intervening 
KbdDeRegister. KbdDeRegister must be issued by the same process that issued the KbdRegister. 

C Language 

Jfdefine INCL_KBD 

USHORT rc = KbdRegister (ModuleName, EntryPoint, FunctionMask); 


PSZ 

ModuleName; 

/* Module name */ 

PSZ 

EntryPoint; 

/* Entry point name */ 

ULONG 

FunctionMask; 

/* Function mask */ 

USHORT 

rc; 

/* return code */ 
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KbdRegister - 
Register Keyboard Subsystem 


Assembler Language 

EXTRN KbdRegister:FAR 
INCL_KBD Equ 1 

PUSH® ASCI IZ ModuleName ; Module name 

PUSH® ASCI IZ Entry Point ; Entry point name 

PUSH DWORD FunctionMask ; Function mask 
CALL KbdRegi ster 

Returns WORD 
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KbdSetCp - 
Set the Code Page 


xPM 


This call allows the process to set the code page used to translate key strokes received from the key- 
board. 


KbdSetCp (Reserved, CodePagelD, KbdHandle) 


Parameters 

Reserved ( USHORT) — input 

Reserved and must be set to zero. 

CodePagelD ( USHORT) - input 

CodePagelD represents a code-page ID in the application’s data area. The code-page ID must be 
equivalent to one of the code-page IDs specified on the CONFIG.SYS CODEPAGE = statement or 
0000. If the code-page ID does not match one of the IDs on the CODEPAGE = statement, an error 
results. The code-page word must have one of these code-page identifiers: 


Identifier 

Description 

0 

Resident code page 

437 

IBM PC US 437 

850 

Multilingual 

860 

Portuguese 

863 

Canadian-French 

865 

Nordic. 

KbdHandle {HKBD) - input 

Default keyboard or the logical keyboard. 

rc ( USHORT) - 

return 

Return code descriptions are: 

0 

NO_ERROR 

439 

ERROR_KBDJNVALID_HANDLE 

445 

ERROR_KBD_FOCUS_REQUIRED 

447 

ERROR J<BD_KEYBOARD_BUSY 

448 

ERRORJ<BDJNVALID_cdDEPAGE 

464 

ERROR_KBD_DET ACHED 

504 

ERROR KBD EXTENDED SG 


Remarks 

Keyboard code page support is not available without the DEVINFO=KBD statement in the CONFIG.SYS 
file. Refer to the IBM Operating System/2 Using the System for a complete description of CODEPAGE and 
DEVINFO. 


C Language 

Idefine INCLJCBD 

USHORT rc = KbdSetCp (Reserved, CodePagelD. KbdHandle); 


USHORT 

Reserved; 

/* Reserved (must be zero) */ 

USHORT 

CodePagelD; 

/* code page ID */ 

HKBD 

KbdHandle; 

/* Keyboard handle */ 

USHORT 

rc; 

/* return code */ 
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xPM 


KbdSetCp - 
Set the Code Page 


Assembler Language 

EXTRN KbdSetCp: FAR 

INCL.KBD EQU 1 

PUSH WORD Reserved Reserved (must be zero) 

PUSH WORD CodePagelD ;code page ID 

PUSH WORD KbdHandle ; Keyboard handle 

CALL KbdSetCp 

Returns WORD 


Chapter 3. Keyboard Function Calls 3-23 



KbdSetCustXt - 

Set Custom Translate Table 


xPM 


This call installs, on the specified handle, the translate table which this call points to. This translate table 
affects only this handle. 


KbdSetCustXt (Xlatetable, KbdHandle) 


Parameters 

Xlatetable ( PUSHORT) - input 

A pointer to the translation table used to translate scan code to ASCII code for a specified handle. 
The format of the translate table is documented in the Set Code Page IOCTL 50H. Refer to IBM Oper- 
ating System/2 Version 1.2 I/O Subsystems And Device Support Volume 1 for a complete discussion 
of Set Code Page IOCTL 50H. 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc ( USHORT) - return 


Return code 

> descriptions are: 

0 

NOJERROR 

377 

ERR0R_KBDJNVAL1D_ECH0_MASK 

378 

ERROR_KBDJNVALID_INPUT_MASK 

439 

ERRORJ<BDJNVALID_HANDLE 

445 

ERROR_KBD_FOCUS_REQUIRED 

447 

ERROR_KBDJ<EYBOARDJBUSY 

464 

ERROR_KBD_DETACHED 

504 

ERROR KBD EXTENDED SG 


Remarks 

The translate table must be maintained in the caller's memory. No copy of the translate table is made by 
KbdSetCustXt. 

KbdSetCp reverses the action of KbdSetCustXt and sets the handle equal to one of the system translate 
tables. If memory is dynamically allocated by the caller for the translate table and is freed before the 
KbdSetCp is performed, KbdSetCp and future translations may fail. 


C Language 

Idefine I NCL_KBD 

USHORT rc = KbdSetCustXt (Xlatetable, KbdHandle); 


PUSHORT 

Xlatetable; 

/* Translation Table */ 

HKBD 

KbdHandle; 

/* Keyboard handle */ 

USHORT 

rc; 

fie return code ief 


Assembler Language 

EXTRN KbdSetCustXt: FAR 
INCL_KBD EQU 1 

PUSH® WORD CodePage ; Translation Table 

PUSH WORD KbdHandle keyboard handle 

CALL KbdSetCustXt 

Returns WORD 
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xPM KbdSetFgnd - 

Set Foreground Keyboard Priority 


This call raises the priority of the foreground keyboard's thread. 


KbdSetFgnd ( ) 


Parameters 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

447 ERROR_KBDJ<EYBOARD_BUSY 

504 ERROR_KBD_EXTENDED_S<3 

Remarks 

KbdSetFgnd marks the current process that owns the keyboard. Threads in this process receive a pri- 
ority boost. The previous foreground keyboard threads lose their priority boost. 

This function should only be issued by a Keyboard Subsystem during KbdCharln or KbdStringln proc- 
essing. 

C Language 

#de fine INCL.KBD 

USHORT rc = KbdSetFgnd(VOIO) ; 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN KbdSetFgnd:FAR 
INCL_KBD EQU 1 

CALL KbdSetFgnd 

Returns WORD 
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KbdSetStatus - 
Set Keyboard Status 


FAP1 xPM 


This call sets the characteristics of the keyboard. 


KbdSetStatus (StatData, KbdHandle) 


Parameters 

StatData ( PKBDINFO ) - input 

Address of the keyboard status structure: 

length ( USHORT) 

Length, in bytes, of this data structure, including length. 

10 Only valid value, 

sysstate (USHORT) 

The system state altered by this call. If bits 0 and 1 are off, the echo state of the system is not 
altered. If bits 2 and 3 are off, the binary and ASCII state of the system is not altered. If bits 0 
and 1 are on, or if bits 2 and 3 are on, the function returns an error. If binary mode is set, echo 
is ignored. 

Bit Description 

15-9 Reserved, set to zero 

8 Shift return is on 

7 Length of the turn-around character (meaningful only if bit 6 is on). 

6 Turn-around character is modified 

5 Interim character flags are modified 

4 Shift state is modified 

3 ASCII mode is on 

2 Binary mode is on 

1 Echo off 

0 Echo on 

turnchardef ( USHORT) 

Definition of the turn-around character. In ASCII and extended-ASCII format, the turn-around 
character is defined as the carriage return. In ASCII format only, the turn-around character is 
defined in the low-order byte. 

intcharflag (USHORT) 

Interim character flags: 

Bit Description 

15-8 NLS shift state. 

7 Interim character flag is on 

6 Reserved, set to zero 

5 Application requested immediate conversion 

4-0 Reserved, set to zero 

shiftstate (USHORT) 


Shift state. 

Bit 

Description 

15 

SysReq key down 

14 

CapsLock key down 

13 

NumLock key down 

12 

Scroll Lock key down 

11 

Right Alt key down 

10 

Right Ctrl key down 

9 

Left Alt key down 

8 

Left Ctrl key down 

7 

Insert on 
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FAPI xPM 


KbdSetStatus - 
Set Keyboard Status 


6 CapsLock on 

5 NumLock on 

4 Scroll Lock on 

3 Either Alt key down 

2 Either Ctrl key down 

1 Left Shift key down 

0 Right Shift key down 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc ( USHORT) - return 

Return code descriptions are: 


0 

NO_ERROR 

376 

ERROR_KBDJNVALID_LENGTH 

377 

ERROR_KBD_INVALID_ECHO_MASK 

378 

ERROR_KBD_INVAUDJNPUT_MASK 

439 

error’kbdjnvaudjhandle 

445 

ERROR_KBD_FOCUS_REQUIRED 

447 

ERROR_KBD_KEYBOARD_BUSY 

464 

ERROR_KBD_DETACHED 

504 

ERROR_KBD_EXTENDED_SG 

Remarks 



Shift return (bit 8 in sysstate) must be disabled in ASCII mode. 

KbdSetStatus is ignored for a Vio-windowed application. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to KbdSetStatus when coding in the DOS mode: 

• KbdSetStatus does not accept a bit mask of 10 (ASCII on, Echo Off). 

• Raw (binary) Mode and Echo On are not supported and return an error If requested. 

• KbdHandle is ignored. 

• Interim character is not supported. 

• Turnaround character is not supported. 

C Language 

typedef struct KBDINFO { 

USHORT cb; 

USHORT fsMask; 

USHORT chTurn Around; 

USHORT fs Interim; 

USHORT fsState; 

}KBDINF0; 

#define INCLJCBD 

USHORT rc = KbdSetStatus (Structure, KbdHandle); 

PKBDINFO Structure; /* Data structure */ 

HKBD KbdHandle; /* Keyboard Handle */ 

USHORT rc; /* return code */ 


/* kbst */ 

/* length in bytes of this structure */ 
/* bit mask of functions to be altered */ 
/* define TurnAround character */ 

/* interim character flags */ 

/* shift states */ 
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KbdSetStatus - 
Set Keyboard Status 


FAPI xPM 


Assembler Language 

KBD1NF0 struc 
kbst_cb dw 

kbst_fsMask dw 

kb$t_chTurnAround dw 
kbst_fs Interim dw 

kbst_fs$tate dw 

KBOINFO ends 

EXTRN KbdSetStatus: FAR 
INCL_KBD EQU 1 

PUSH? OTHER Structure ;Data structure 

PUSH WORD KbdHandle ; Keyboard Handle 

CALL KbdSetStatus 

Returns WORD 


? ; length in bytes of this structure 
? ;bit mask of functions to be altered 
? ; define TurnAround character 
? ; interim character flags 
? ; shift states 
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FAPI xPM 


KbdStringln - 
Read Character String 


This call reads a character string (character codes only) from the keyboard. 


KbdStringln (CharBuffer, StringLength, lOWait, KbdHandle) 


Parameters 

CharBuffer ( PCH ) - output 

Address of the character string buffer. 

StringLength ( PSTRINGINBUF ) - input/output 

Address of the length of the character string buffer. On entry, buflen is the maximum length, in 
bytes, of the buffer. The maximum length that can be specified is 255. Template processing has 
meaning only in the ASCII mode. 

buflen (USHORT) 

Length of the input buffer. 

inputlen (USHORT) 

Number of bytes read into the buffer. 

lOWait ( USHORT) - input 

Wait if a character is not available. 

Value Definition 

0 Wait. In Binary input mode, the requestor waits until CharBuffer is full. In ASCII input 
mode, the requestor waits until a carriage return is pressed. 

1 No wait. The requestor gets an immediate return if no characters are available. If char- 
acters are available, KbdStringln returns immediately with as many characters as are 
available (up to the maximum). No wait is not supported in ASCII input mode. 

KbdHandle (HKBD) - input 

Default keyboard or the logical keyboard. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

375 ERROR J<BDJNVALID_IOWA!T 

439 ERROR_KBD_INVALID_HANDLE 

445 ERROR_KBD_FOCUS_REQUIRED 

464 ERROR J<BD_DETACHED 

504 ERROR_KBD_EXTENDED_SG 

Remarks 

The character strings may be optionally echoed on the display if echo mode is set. When echo is on each 
character is echoed as it is read from the keyboard. Echo mode and BINARY mode are mutually exclu- 
sive. Reference KbdSetStatus and KbdGetStatus for more information. 

The default input mode is ASCII. In ASCII mode, 2-byte character codes only return in complete form. An 
extended ASCII code is returned in a 2-byte string. The first byte is ODH or EOH and the next byte is an 
extended code. 

In input mode (BINARY, ASCII), The following returns can be set and retrieved with KbdSetStatus and 
KbdGetStatus: 

Turnaround Character 
Echo Mode 

Interim Character Flag 
Shift State 
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KbdStringln - 
Read Character String 


FAPI xPM 


The received input length is also used by the KbdStringln line edit functions for re-displaying and 
entering a caller specified string. On the next KbdStringln call the received input length indicates the 
length of the input buffer that may be recalled by the user using the line editing keys. A value of 0 inhibits 
the line editing function for the current KbdStringln request. 

KbdStringln completes when the handle has access to the physical keyboard (focus), or is equal to zero 
and no other handle has the focus. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restrictions apply to KbdStringln when coding in the DOS mode: 

* KbdHandle is ignored 

Refer to the DosRead Family API Considerations for differences between DOS and OS/2 node when 
reading from a handle opened to the CON device. 

C Language 

typedef struct _STRINGINBUF { /* kbsi */ 

USHORT cb; /* input buffer length */ 

USHORT cchln; /* received input length */ 

} STRINGINBUF; 

#define INCLJ<BD 

USHORT rc = KbdStringIn(CharBuffer, Length, IOWait, KbdHandle); 

PCH CharBuffer; /* Char string buffer */ 

PSTRINGINBUF Length; /* Length table */ 

USHORT IOWait; /* Indicate if wait for char */ 

HKBD KbdHandle; /* Keyboard handle */ 

USHORT rc; /* return code */ 

Assembler Language 

STRINGINBUF struc 

kbsi_cb dw ? ; input buffer length 
kbsi_cchln dw ? ; received input length 
STRINGINBUF ends 

EXTRN KbdStringln: FAR 
INCLJCBD EQU 1 

PUSH@ OTHER CharBuffer ;Char string buffer 

PUSH® OTHER Length ; Length table 

PUSH WORD IOWait indicate if wait for char 

PUSH WORD KbdHandle ; Keyboard handle 

CALL KbdStringln 

Returns WORD 
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xwpm KbdSynch - 

Synchronize Keyboard Access 


This call synchronizes access from a keyboard subsystem to the keyboard device driver. 


KbdSynch (lOWalt) 


Parameters 

lOWait ( USHORT) - input 

Wait for the bond. Values are: 

Value Definition 

0 Indicates the requestor does not wait for access to the device driver. 

1 Indicates the requestor waits for access to the device driver. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

121 ERROR_SEM_TIMEOUT 

Remarks 

KbdSynch blocks ail other threads within a session until return from the subsystem to the router. To 
ensure proper synchronization, KbdSynch should be issued by a keyboard subsystem if it intends to 
issue a DosDeviOCtl or access dynamically shared data. KbdSynch does not protect globally shared data 
from threads in other sessions. 

C Language 

#define INCLJBD 

USHORT rc = KbdSynch (IOWait); 

USHORT IOWait; /* Indicate if wait */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN KbdSynch: FAR 
INCLJBD EQU 1 

PUSH WORD IOWait ; Indicate if wait 

CALL KbdSynch 

Returns WORD 
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KbdXIate - 
Translate Scan Code 


XPM 


This call translates scan codes with shift states into ASCII codes. 


KbdXIate (XlateRecord, KbdHandle) 


Parameters 

XlateRecord ( PKBDTRANS ) - input 

Address of the translation record structure: 

chardata ( KBDKEYINFO ) 

Character data information structure as defined in KbdCharln call, 
kbdflag ( USHORT) 

See the KbdDDFIagWord call in the "Keyboard Device Driver” section of IBM Operating 
System/2 Version 1.2 I/O Subsystems And Device Support Volume 1. 

xlate (USHORT) 

Translation flag: 

Value Definition 

0 Translation incomplete. 

1 Translation complete. 

xlatestatel (USHORT) 

Identifies the state of translation across successive calls; initially the value should be zero. It 
may take several calls to this function to complete a character. The value should not be 
changed unless a new translation is required, that is, reset value to zero. 

xlatestate2 (USHORT) 

See description for xlatestatel. 

KbdHandle ( HKBD ) - input 

Default keyboard or the logical keyboard. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

439 ERROR_KBD_INVAUD_HANDLE 

445 ERROR_KBD_FOCUS_REQUIRED 

447 ERROR_KBD_KEYBOARD_BUSY 

464 ERROR_KBDJDETACHED 

504 ERROR_KBD~EXTENDED_SG 

Remarks 

It may take several calls to complete a translation because of accent key combinations, or other complex 
operations. 

The Xlatestatel and Xlatestate2 are for use by the keyboard translation routines. These fields are 
reserved and must only be accessed by the caller prior to starting a translation sequence and then they 
must be set to zero. The KbdXIate function is intended to be used for translating a particular scan code 
for a given shift state. The KbdXIate function is not intended to be a replacement for the OS/2 system 
keystroke translation function. 
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xPM 


KbdXIate - 
Translate Scan Code 


C Language 

typedef struct _KBDTRANS { /* kbxl */ 


UCHAR 

chChar; 

/* ASCII character code */ 

UCHAR 

chScan; 

/* Scan code */ 

UCHAR 

fbStatus; 

/* State of the character */ 

UCHAR 

bNlsShift; 

/* Shift status (reserved set to zero) */ 

USHORT 

fsState; 

fie Shift state ie/ 

ULONG 

time; 


USHORT 

fsDD; 


USHORT 

fsXlate; 


USHORT 

fsShift; 


USHORT 

sZero; 


} KBDTRANS; 




#define INCL_KBD 

USHORT rc = KbdXlate(XlateRecord f KbdHandle); 

PKBDTRANS XlateRecord; /* Translation Record */ 

HKBD KbdHandle; /* Keyboard handle */ 

USHORT rc; /* return code */ 


Assembler Language 

KBDTRANS struc 

kbxl_chChar db ? ;ASCII character code 

kbxl_ch$can db ? ;scan code 

kbxl_fbStatus db ? ;State of the character 

kbxl _bN1$Shift db ? ;shift status (reserved set to zero) 

kbxl_fsState dw ? ;shi ft state 

kbxl_time dd ? 

kbxljfsDD dw ? 

kbxl_fsXlate dw ? 

kbxl_fsShift dw ? 

kbxl_sZero dw ? 

KBDTRANS ends 

EXTRN KbdXIate: FAR 

INCLJBD EQU 1 

PUSH© OTHER XlateRecord translation Record 

PUSH WORD KbdHandle keyboard handle 

CALL KbdXIate 

Returns WORD 


Chapter 3. Keyboard Function Calls 3-33 



3-34 


Control Program Programming Reference 



Chapter 4. Mouse Function Calls 


This chapter reflects the Mouse API interface of OS/2 only. 

For information regarding mouse device drivers, mouse pointer draw device, mouse installation and 
mouse lOCTLs, refer to IBM Operating System/2 Version 1.2 I/O Subsystems And Device Support Volume 
1 . 

Notes: 

1. Calls marked xPM are not supported by Presentation Manager, and must not be used by Presenta- 
tion Manager applications. An error code is returned if any of these calls are issued. 

2. Calls marked xWPM are not windowable and are not supported by Presentation Manager. They can 
be used in OS/2 mode. 

3. Calls marked FAPI are present in the Family API. 

4. Those calls without an icon are: 

• Windowable 

• Presentation Manager 

• Full-screen 

• Not Family API. 
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MouClose - 
Close Mouse Device 


xPM 


This call closes the mouse device for the current session. 


MouClose (DeviceHandle) 


Parameters 

DeviceHandle ( HMOU ) - input 

Mouse device handle from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DiTACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

MouClose closes the mouse device for the current session and removes the mouse device driver handle 
from the list of valid open mouse device handles. 

C Language 

#define INCL_M0U 

USHORT rc = MouClose(DeviceHandle) ; 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouClose: FAR 
INCL_M0U EQU 1 

PUSH WORD DeviceHandle ;Mouse device handle 
CALL MouClose 

Returns WORD 
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xWPM 


MouDeRegister - 
Deregister a Subsystem 


This call deregisters a mouse subsystem previously registered within a session. 


MouDeRegister ( ) 


Parameters 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

416 ERROR_MOUSE_DEREGISTER 

466 ERROR_MOU_DETACHED 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

Processes issuing MouDeRegister calls must conform to the following rules: 

• The process that issued the MouRegister must release the session (by a MouDeRegister) from the 
registered subsystem before another P!D may issue MouRegister. 

• The process that issued the MouRegister is the only process that may issue MouDeRegister against 
the currently registered subsystem. 

• After the owning process has released the subsystem with a MouDeRegister, any other process in 
the session may issue a MouRegister and therefore modify the mouse support for the entire session. 

C Language 

Idefine INCL_M0U 

USHORT rc = MouDeRegister(VOIO); 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouDeRegister: FAR 
INCLMOU EQU 1 

CALL MouDeRegister 

Returns WORD 
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MouDrawPtr - 
Mouse Draw Pointer 


xPM 


This call allows a process to notify the mouse device driver that an area previously restricted to the 
pointer image is now available to the mouse device driver. 


MouDrawPtr (DevIceHandle) 


Parameters 

DevIceHandle (HMOU) - input 

Mouse device handle from a previous MouOpen. 

rc (USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

The collision area (the pointer image restricted area) is established by MouOpen and by MouRemovePtr. 
MouDrawPtr nullifies the effect of the MouRemovePtr command. If there was no previous MouDrawPtr 
command or if a previous MouDrawPtr command has already nullified the collision area, the 
MouRemovePtr command is effectively a null operation. 

This call is required to begin session pointer image drawing. Immediately after MouOpen is issued, the 
collision area is defined as the size of the display. A MouDrawPtr is issued to begin pointer drawing after 
the MouOpen. 

C Language 

Ideflne INCl_M0U 

USHORT rc = MouDrawPtr(DeviceHandle) ; 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouDrawPtr:FAR 
INCL_M0U EQU 1 

PUSH WORD DeviceHandle ;Mouse device handle 
CALL MouDrawPtr 

Returns WORD 
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xPM 


MouFlushQue - 
Flush Mouse Queue 


This call directs the mouse driver to flush (empty) the mouse event queue and the monitor chain data for 
the session. 


MouFlushQue (DevIceHandle) 


Parameters 

DevIceHandle (HMOU) - input 

Mouse device handle from a previous MouOpen. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DET ACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOUJEXTENDED_SG 


C Language 

Idefine INCL_M0U 

USHORT rc = MouFlushQue (Devi ceHandle): 

HMOU Devi ceHandle; fie Mouse device handle */ 

USHORT rc; fie return code ief 

Assembler Language 

EXTRN MouFlushQue: FAR 
INCI_M0U EQU 1 

PUSH WORD Devi ceHandle ; Mouse device handle 

CALL MouFlushQue 

Returns WORD 
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MouGetDevStatus - 
Get Mouse Device Status 


xPM 


This call returns status flags for the installed mouse device driver. 


MouGetDevStatus (DevfceStatus, DeviceHandle) 

Parameters 

DevIceStatus (PUSHORT) - output 

Address of the current status flag settings for the installed mouse device driver. 

The return value is a 2-byte set of bit flags. 

Bit Description 

15-10 Reserved, set to zero. 

9 Set if mouse data returned in mickeys, not pels. 

8 Set if the drawing operations for pointer draw routine are disabled. 

7-4 Reserved, set to zero. 

3 Set if pointer draw routine disabled by unsupported mode. 

2 Set if flush in progress. 

1 Set if block read in progress. 

0 Set if event queue busy with I/O. 

DeviceHandle (HMOU) - input 

Mouse device handle from a previous MouOpen. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO.ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOUJDETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

C Language 

^define INCL_M0U 

USHORT rc = MouGetDevStatus (DevIceStatus, DeviceHandle); 

PUSHORT DeviceStatus; /* Current status flags */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouGetDevStatus :FAR 
INCL_M0U EQU 1 

PUSH@ WORD DeviceStatus ; Current status flags 
PUSH WORD DeviceHandle ;Mouse device handle 
CALL MouGetDevStatus 

Returns WORD 
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xPM 


MouGetEventMask - 
Get Mouse Event Mask 


This call returns the current value of the mouse event queue mask. 


MouGetEventMask (EventMask, DevIceHandle) 

Parameters 

EventMask (PUSHORT) - output 

Address in application storage where the current mouse device driver's event mask is returned to 
the caller by the mouse device driver. 

The EventMask is set by MouSetEventMask, and has the following definition: 

Bit Description 

15-7 Reserved, set to zero. 

6 Set to report button 3 press/release events, without mouse motion. 

5 Set to report button 3 press/release events, with mouse motion. 

4 Set to report button 2 press/release events, without mouse motion. 

3 Set to report button 2 press/release events, with mouse motion. 

2 Set to report button 1 press/release events, without mouse motion. 

1 Set to report button 1 press/release events, with mouse motion. 

0 Set to report mouse motion events with no button press/release events. 

DeviceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

Buttons are logically numbered from left to right. 

C Language 

Idefine INCL_M0U 

USHORT rc = MouGetEventMask(EventMask» DeviceHandle); 

PUSHORT EventMask; /* Event Mask word */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /is return code is/ 

Assembler Language 

EXTRN MouGetEventMask : FAR 
INCL_M0U EQU 1 

PUSH® WORD EventMask ; Event Mask word 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouGetEventMask 

Returns WORD 
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MouGetNumButtons - 
Get Number of Mouse Buttons 


xPM 


This call returns the number of buttons supported on the installed mouse driver. 


MouGetNumButtons (NumberOfButtons, DevIceHandle) 


Parameters 

NumberOfButtons ( PUSHORT) - output 

Address of the number of physical buttons. The return values for the number of buttons supported 
are: 

Value Definition 

1 One mouse button 

2 Two mouse buttons 

3 Three mouse buttons. 

DevIceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

C Language 

Idefine INCL_M0U 

USHORT rc = MouGetNumButtons (NumberOfButtons, DeviceHandle) ; 

PUSHORT NumberOfButtons; /* Number of mouse buttons */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouGetNumButtons: FAR 
INCL_M0U EQU 1 

PUSH@ WORD NumberOfButtons ; Number of mouse buttons 
PUSH WORD DeviceHandle ;Mouse device handle 
CALL MouGetNumButtons 

Returns WORD 
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xPM 


MouGetNumMickeys - 
Get Number off Mouse Mickeys 


This call returns the number of mickeys in each centimeter for the installed mouse driver. 


MouGetNumMickeys (NumberOffMickeys, DeviceHandle) 


Parameters 


NumberOffMickeys ( PUSHORT) - output 

Address of the number of physical mouse motion units. Mouse motion units are reported in mickeys 
in each centimeter. This value is constant based upon the mouse device attached. 

DeviceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc (USHORT) - return 

Return code descriptions are: 


0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DET ACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 


C Language 

Idefine INCL_M0U 

USHORT rc = MouGet NumMic key s(NumberOf Mickeys, DeviceHandle); 

PUSHORT NumberOf Mickeys; /* Number mi ckeys/centi meter */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouGetNumMickeys: FAR 
INCL_M0U EQU 1 

PUSH® WORD NumberOf Mickeys ; Number mi ckeys/centi meter 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouGetNumMickeys 

Returns WORD 
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MouGetNumQueEl — 
Get Event Queue Status 


xPM 


This call returns the current status for the mouse device driver event queue. 

MouGetNumQueEl (QueDataRecord, DeviceHandle) 

Parameters 

QueDataRecord ( PMOUQUEINFO ) - output 

Address of the mouse queue status structure: 

numqelements (USHORT) 

Current number of event queue elements, in the range 0 < value < maxnumqelements. 
maxnumqelements ( USHORT) 

Maximum number of queue elements as specified in the QSIZE = NN parameter in 
DEVICE=MOUSExxx.SYS statement in CONFIG.SYS. 

DeviceHandle (HMOU) - input 

Contains the handle of the mouse device obtained from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDEDSG 

Remarks 

The maxnumqelements returned by this function is established during mouse device driver configuration. 
See the mouse DEVICE=MOUSExxx.SYS statement in the IBM Operating System/2 Version 1.2 Command 
Reference for further details. 

C Language 

typedef struct _M0UQUEINF0 { /* mouqi */ 

USHORT cE vents; /* current number of event queue elements */ 

USHORT cmaxEvents; /* MaxNumQueEl ements value */ 

} MOUQUEINFO; 

#define INCLJIOU 

USHORT rc - MouGetNumQueEl (QueDataRecord, DeviceHandle); 

PMOUQUEINFO QueDataRecord; /* Ptr to 2-word structure is/ 

HMOU DeviceHandle; /* Mouse device handle is/ 

USHORT rc; /is return code is/ 
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xPM 


MouGetNumQueEl - 
Get Event Queue Status 


Assembler Language 

MOUQUEINFO struc 

mouqi_cEvents dw ? ; current number of event queue elements 
mouqi cmaxE vents dw ? ;MaxNumQueElements value 
MOUQUEINFO ends 

EXTRN MouGetNumQueEl: FAR 
INCL_M0U EQU 1 

PUSH? OTHER QueDataRecord ;Ptr to 2-word structure 

PUSH WORD OeviceHandle ; Mouse device handle 

CALL MouGetNumQueEl 

Returns WORD 
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MouGetPtrPos - 

Query Mouse Pointer Position 


xPM 


This call queries the mouse driver to determine the current row and column coordinate position of the 
mouse pointer 


MouGetPtrPos (PtrPos, DeviceHandle) 


Parameters 

PtrPos ( PPTRLOC ) - output 

Address of the mouse pointer position structure: 

polnterrow ( USHORT) 

Current pointer row coordinate (pels or characters), 
pointercol (USHORT) 

Current pointer column coordinate (pels or characters). 

DeviceHandle (HMOU) - input 

Contains the handle of the mouse device obtained from a previous MouOpen. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR’mOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

For a text window (VIO) application, the text window is a view on the larger logical video buffer (LVB). 
The mouse pointer can be outside that view and still be within the extent of the LVB. MouGetPtrPos then 
returns the coordinates of the cell under the mouse pointer. If the pointer is outside the LVB image 
extent, the coordinates of the nearest LVB cell are returned. In either case, the LVB is scrolled until the 
reported LVB cell appears within the view window. 

C Language 

typedef struct _PTRL0C { 

USHORT row; 

USHORT col ; 

} PTRLOC; 


Idefine INCL_M0U 

USHORT rc = MouGetPtrPos (PtrPos, DeviceHandle); 


PPTRLOC 

PtrPos; 

/* Double word structure */ 

HMOU 

DeviceHandle; 

/* Mouse device handle */ 

USHORT 

rc; 

/* return code */ 


/* moupl */ 

/* pointer row coordinate screen 
position */ 

/* pointer column coordinate screen 
position */ 
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xpm MouGetPtrPos - 

Query Mouse Pointer Position 


Assembler Language 

PTRLOC st rue 

moupljrow dw ? ; pointer row coordinate screen position 
moupl_col dw ? ;pointer column coordinate screen position 
PTRLOC ends 

EXTRN MouGetPtrPos: FAR 
INCL.M0U EQU 1 

PUSH® OTHER PtrPos ; Double word structure 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouGetPtrPos 

Returns WORD 
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MouGetPtrShape - xpm 

Get Pointer Shape 


This call allows a process to get (copy) the pointer shape for the session. 


MouGetPtrShape (PtrBuffer, PtrDefRec, DeviceHandle) 


Parameters 

PtrBuffer (PBYTE) - output 

Address of an area in application storage where the pointer draw device driver returns the pointer 
bit image. See MouSetPtrShape "MouSetPtrShape - Set Mouse Pointer Shape" on page 4-37 for 
a further description of the resulting content of this buffer. 

PtrDefRec ( PPTRSHAPE ) — input/output 

Address of a structure in application storage where the application stores the data necessary for the 
pointer device driver to return information about the Row by Col image for each bit plane for the 
mode the display is currently running. See MouSetPtrShape for a further description of the contents 
of this structure. 

TotLength (USHORT) 

Length of the pointer buffer available for the pointer device driver to build a Row by Col image 
for each bit plane for the mode the display is currently running. This value is supplied by the 
application. If the value is too small, pointer draw places the true length of the image in this 
field, and returns an error. 

For all OS/2 system-supported modes, TotLength is specified in bytes and is equal to: 

Mono & Text Modes For text mode height and width must be 1, so length is always 4. 

TotLength = (height in chars) * (width in chars) *2*2 
= 1 * 1 * 2 * 2 
= 4 

Graphics Mode Width-in-pels must be a multiple of 8. 

TotLength - (height in pels)*(width in pels)*(bits per pel)*2 / 8 
Modes 4 and 5 (320 X 200) 

TotLength = (height) * (width) *2*2/8 

Mode 6 (640 X 200) 

TotLength = (height) * (width) *1*2/8 
Length calculations produce byte boundary buffer sizes. 

col (USHORT) 

Number of columns in the mouse shape. In graphics modes, this field contains the pel width 
(columns) of the mouse shape for the session and must be greater than or equal to 1. In text 
modes, col must equal 1. 

row ( USHORT) 

Number of rows in the mouse shape. In graphics modes, this field contains the pel height (rows) 
of the mouse shape for the session and must be greater than or equal to 1. In text modes, row 
must equal 1. 

coloffset (USHORT) 

This value is returned by the mouse device driver to indicate the relative column offset within 
the pointer image. The value defines the center (hotspot) of the pointer image. This value is a 
signed number that represents either character or pel offset, depending on the display mode. 

rowoffset (USHORT) 

This value is returned by the mouse device driver to indicate the relative row offset within the 
pointer image. The value defines the center (hotspot) of the pointer image. This value is a 
signed number that represents either character or pel offset, depending on the display mode. 
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xPM 


MouGetPtrShape - 
Get Pointer Shape 


DeviceHandle ( HMOU ) - input 

Handle of the mouse device from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NCLERROR 

385 ERROR_MOUSE_NO_DEVICE 

387 ERROR_MOUSEJNV_PARMS 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

The application passes a parameter list with the same meaning as defined for MouSetPtrShape to the 
mouse device driver. The mouse device driver copies the parameters that describe the pointer shape 
and attributes into the pointer definition control block pointed to by the PtrDefRec parameter. The word 0 
(buffer length = TotLength) pointer definition record parameter field must contain the size in bytes of the 
application buffer where the device driver is to insert the sessions pointer image. All other words in the 
parameter list are returned to the application by MouGetPtrShape. 

If the buffer size is insufficient, the TotLength field contains the actual size in bytes of the returned pointer 
image. 

The pointer shape may be set by the application with MouSetPtrShape or may be the default image pro- 
vided by the installed Pointer Device Driver. 

C Language 

typedef struct PTRSHAPE { 

USHORT cb; 

USHORT col ; 

USHORT row; 

USHORT col Hot; 

USHORT rowHot; 

} PTRSHAPE; 


Idefine INCL_M0U 

USHORT rc = MouGetPtrShape(PtrBuffer, PtrDefRec, DeviceHandle); 


PBYTE 

PtrBuffer; 

/* Pointer shape buffer */ 

PPTRSHAPE 

PtrDefRec; 

/* Pointer definition struct */ 

HMOU 

DeviceHandle; 

/* Mouse device handle */ 

USHORT 

rc; 

/* return code */ 


/* moups */ 

/* total length necessary to build image */ 
/* # of columns in mouse shape */ 

/* number of rows in mouse shape */ 

/* column coordinate of pointer image 
hotspot */ 

/* row coordinate of pointer image 
hotspot */ 
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MouGetPtrShape 
Get Pointer Shape 


xPM 


Assembler Language 

PTRSHAPE struc 

moups_cb dw ? ; total length necessary to build image 

moups_col dw ? ;# of columns in mouse shape 

moupsjrow dw ? ; number of rows in mouse shape 

moup$_col Hot dw ? ; column coordinate of pointer image hotspot 

moups_rowHot dw ? ;row coordinate of pointer image hotspot 

PTRSHAPE ends 

EXTRN MouGetPtrShape: FAR 
INCL_M0U EQU 1 

PUSH® OTHER PtrBuffer ; Pointer shape buffer 

PUSH® OTHER PtrDefRec ; Pointer definition struct 

PUSH WORD DeviceHandle ; Mouse device handle 

CALL MouGetPtrShape 

Returns WORD 
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MouGetScaleFact - 
Get Mouse Scaling Factors 


This call returns a pair of 1-word scaling factors for the current mouse device. 


MouGetScaleFact (ScaleStruct, DevIceHandle) 


Parameters 

ScaleStruct ( PSCALEFACT) - output 

Address of the control block structure that contains the current row and column coordinate scaling 
factors. The scaling factors must be greater than or equal to 1 and less than or equal to (32K — 1). 

rowscale (USHORT) 

Row scaling factor. 

colscale (USHORT) 

Column scaling factor. 

See "MouSetScaleFact - Set Mouse Scaling Factor” on page 4-40 for more information. 
DevIceHandle ( HMOU ) - input 

Contains the handle of the mouse device obtained from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEV1CE 

466 ERROR J/IOU_DETACHED 

501 E R ROR_M OUSE_N 0_C0 NSO LE 

505 ERROR_MOUEXTENDED_SG 

Remarks 

The units of the scale factor depend on the mode of the display screen for the session. If the screen is 
operating in text mode, the scaling units are relative to characters. If the screen is operating In graphics 
mode, the scaling units are relative to pels. 

C Language 

typedef struct _SCALEFACT { 

USHORT rowScaTe; 

USHORT col Scale; 

} SCALEFACT; 

#define INCLJ10U 

USHORT rc a MouGetScaleFact (ScaleStruct, DeviceHandle); 

PSCALEFACT ScaleStruct; /* 2-word structure */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 


/* mouse */ 

/* row scaling factor */ 

/* column coordinate scaling factor */ 
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Assembler Language 

SCALEFACT struc 

mouscjrowScal e dw ? ;row scaling factor 
mousc_col Scale dw ? ; column coordinate scaling factor 
SCALEFACT ends 


EXTRN 

MouGetScal eFact : FAR 


INCL_M0U 

EQU 1 


PUSH@ 

OTHER 

ScaleStruct 

; 2-word structure 

PUSH 

WORD 

DeviceHandle 

;Mouse device handle 

CALL 

MouGetScaleFact 



Returns WORD 
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MoulnitReal - 
Initialize DOS mode 


This call initializes mouse pointer draw support for DOS mode. 


MoulnitReal (DrfverName) 


Parameters 

DrlverName (PSZ) - input 

Address of the name of the Pointer Draw Device Driver used as the pointer-image drawing routine 
for the DOS mode session. 

The name of the device driver must be included in the CONFIG.SYS file at system start-up time. 

If the selector portion of the far address is zero and the offset portion is non-zero, the offset portion 
identifies the power-up display configuration. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DETACHED 

412 ERROR_MOUSE_SMG_ONLY 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

MoulnitReal is issued by the Base Video Subsystem at system initialization time. 

The DOS mode mouse API (I NT 33H), in contrast to the OS/2 mode Mouse API, does not contain an OPEN 
command. In addition, there is only one session for DOS mode. 

The default pointer draw routine for DOS mode is located in the same pointer draw device driver, 
POINTERS, that is used for OS/2 mode. Establishing addressability to the pointer draw routine must be 
done during system initialization. This requires passing the entry point of the DOS mode pointer draw 
routine to the mouse device driver. This is the purpose of the MoulnitReal call. It passes the address of 
the default, power-up pointer draw routine for DOS mode to the mouse device driver. This initialization is 
transparent to applications. 

This call is for use only by the Base Video Subsystem when invoked during system initialization under the 
shell/session manager PID. 

The error code ERROR_MOUSE_SMG_ONLY is valid from shell process only. 


C Language 

#define INCL.MOU 

USHORT rc = MoulnitReal (Dr iverName) ; 


PSZ 

Dri verNarne; 

/* Pointer draw driver name */ 

USHORT 

rc; 

/* return code */ 
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Initialize DOS mode 
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Assembler Language 

EXTRN MoulnitReal :FAR 
INCL_M0U EQU 1 

PUSH0 ASCI IZ DriverName ; Pointer draw driver name 
CALL MoulnitReal 

Returns WORD 
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MouOpen - 
Open Mouse Device 


This call opens the mouse device for the current session. 


MouOpen (DriverName, DevIceHandle) 


Parameters 

DriverName (PSZ) - input 

DriverName is a far pointer to an ASCIIZ string in application storage containing the name of the 
pointer draw device driver to be used as the pointer-image drawing routine for this session. 

The name of the device driver must be included in the CONFIG.SYS file at system start-up time. 
Applications that use the default pointer draw device driver supplied by the system must push a 
double-word of Os in place of an address. 

DriverName has a different definition when the caller is the Base Video Subsystem (BVS). In this 
case the selector portion of the far address is zero. The offset portion is non-zero and contains a 
display configuration number (sequentially numbered where 1 is the first display configuration). The 
MouOpen call issued by BVS is executed on the VioSetMode path. Using the display configuration 
number passed on the MouOpen call, the Base Mouse Subsystem can detect a change in display 
configurations. This form of the MouOpen call is not recommended for applications. Applications 
should either push the far address of an ASCIIZ pointer draw device driver name or push two words 
of zeros. 

DevIceHandle (PHMOU) - output 

Address of a 1-word value that represents the mouse handle returned to the application. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

390 E R RO R_M OUSE _l N V_M O D U LE_PT 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

MouOpen initializes the Mouse functions to a known state. The application may have to issue additional 
mouse functions to establish the environment it desires. For example, after the MouOpen, the collision 
area is defined to be the size of the entire display. Therefore, to get the pointer to be displayed, the 
application must issue a MouDrawPtr to remove the collision area. 

The state of the mouse after the first MouOpen is: 

• Row/Col scale factors set to 16/8. (See "MouSetScaleFact — Set Mouse Scaling Factor” on 
page 4-40.) 

• All events reported. (See “MouSetEventMask - Set Mouse Event Mask” on page 4-33.) 

• Empty event queue. (See "MouReadEventQue — Read Mouse Event Queue” on page 4-23 and 
“MouGetNumQueEl - Get Event Queue Status” on page 4-10.) 

• All user settable Device Status bits reset. (Set to zero. See ” MouSetDevStatus — Set Mouse 
Device Status" on page 4-31.) 

• Pointer set to center of screen if valid display mode is set. (See “MouSetPtrPos - Set Mouse 
Pointer Position" on page 4-35.) 

• Pointer shape set to the default for the pointer device driver currently registered in the session. (See 
"MouSetPtrShape - Set Mouse Pointer Shape” on page 4-37.) 

• Collision area equal to full screen. (See “MouDrawPtr — Mouse Draw Pointer" on page 4-4 and 
“MouRemovePtr - Remove Mouse Pointer” on page 4-29.) 
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MouOpen - 
Open Mouse Device 


C Language 

#define INCL_M0U 

USHORT re = MouOpen (DriverName, DeviceHandle); 

PSZ DriverName; /*■ Pointer draw driver name */ 

PHMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouOpen: FAR 
INCL_M0U EQU 1 

PUSH@ ASCI 12 DriverName ; Pointer draw driver name 

PUSH@ WORD DeviceHandle ;Mouse device handle 

CALL MouOpen 

Returns WORD 
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MouReadEventQue - 
Read Mouse Event Queue 


This call reads an event from the mouse device FIFO event queue, and places it in a structure provided 
by the application. 


MouReadEventQue (Buffer, ReadType, DeviceHandle) 


Parameters 

Buffer ( PMOUEVENTINFO ) - output 

Address of the status of the mouse event queue. 

moustate ( USHORT) 

State of the mouse at the time of the event. 

Bit Description 

15-7 Reserved, set to zero. 

6 Set if button 3 is down. 

5 Set if mouse is moving and button 3 is down. 

4 Set if button 2 is down. 

3 Set if mouse is moving and button 2 is down. 

2 Set if button 1 is down. 

1 Set if mouse is moving and button 1 is down. 

0 Set if mouse is moving and no buttons are down. 

eventtime (ULONG) 

Time stamp (in milliseconds) since the system was started, 
row ( USHORT) 

Absolute or relative row position, 
col ( USHORT) 

Absolute or relative column position. 

ReadType (PUSHORT) - input 

Address of the action to take when MouReadEventQue is issued and the mouse event queue is 
empty. If the mouse event queue is not empty, this parameter is not examined by the mouse support. 
ReadType values are: 

Value Definition 

0 No Wait for data on empty queue (return a NULL record) 

1 WAIT for data on empty queue. 

DeviceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc (USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

385 ERROR_MOUSE_NO_DEVICE 

387 ERROR_MOUSE_INV_PARMS 

393 E R RO R_M OUS E_NO_D AT A 

466 ERROR_MOU_DET ACHED 

501 E R RO R_M OUSE_N 0_C0 NSO LE 

505 E R ROR_M OU_EXTEN DE D_SG 
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MouReadEventQue - 
Read Mouse Event Queue 
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Remarks 

The types of queued events are directly affected by the current value of the Mouse EventMask. 
MouSetEventMask is used to indicate the types of events desired, and MouGetEventMask is used to 
query the current value of the mask. Refer to these functions for further explanation of the masking of 
events. 

Recognition of the mouse transition depends on the use of MouState returned in the event record. The 
application should focus on bit transitions that occur in this word. It is important to properly set the event 
mask with MouSetEventMask for reporting the state transitions. 

MouState reports the state of the mouse that resulted from the action that caused the event. The action 
can be pressing or releasing a button, and/or moving the mouse. All status is given, regardless of the 
EventMask that was used to determine whether or not to report the event. 

For example, assume the EventMask indicates that the application wishes only button 1 events. The 
EventMask has only bits 1 and 2 set in this case. Also assume the current state of the mouse is no 
buttons down, and mouse is not moving. At this point, button 1 is pressed causing an event; the status 
shows button 1 down (bit 2 set). Next the mouse is moved, thereby causing more events; status shows bit 
1 set. Finally, mouse is stopped and button 1 is released. The event shows status with no bits set. 

Next, button 2 is pressed. No event occurs. Mouse is then moved; again, no event. Then, while mouse is 
still in motion, button 1 is pressed; an event is generated with bits 1 and 3 set in the state word. While 
mouse is still in motion, both buttons are released. Because button 1 changes states, an event occurs. 
The state word has bit 0 set. Finally, mouse is stopped. No event occurs, again because no button 1 
transition has taken place. 

The Row and Column fields in the Buffer Parameter may contain either absolute display coordinates or 
relative mouse motion in mickeys. See MouSetDevStatus for additional information. 

C Language 

typedef struct _M0UEVENTINF0 { /* mouev */ 

USHORT fs; /* State of mouse at time event was 

reported */ 

ULONG time; /* Time since boot in milliseconds */ 

USHORT row; /* Absolute/relative row position */ 

USHORT col; /* Absolute/relative column position */ 

}M0UEVENTINF0; 

#define INCL_M0U 

USHORT rc s MouReadEventQue(Buffer, ReadType, OeviceHandle) ; 

PMOUEVENTINFO Buffer; /* 10 byte Structure address */ 

PUSHORT ReadType; /* Read type */ 

HMOU OeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 
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Read Mouse Event Queue 


Assembler Language 


MOUEVENTINFO struc 
mouevjfs dw ? 
mouevJ:ime dd ? 
mouev_row dw ? 
mouev_col dw ? 
MOUEVENTINFO ends 


;State of mouse at time event was reported 
;time since boot in milliseconds 
; absolute/relative row position 
jabsolute/relative column position 


EXTRN 

MouReadEventQue : FAR 


INCL_M0U 

EQU 1 


PUSHO 

OTHER 

Buffer 

; 10 byte Structure address 

PUSHO 

WORD 

ReadType 

;Read type 

PUSH 

WORD 

DeviceHandle 

;Mouse device handle 

CALL 

MouReadEventQue 



Returns WORD 
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MouRegister - 
Register a Subsystem 
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This call registers a mouse subsystem within a session. 


MouRegister (ModuleName, EntryName, Mask) 


Parameters 


ModuleName (PSZ) - input 

Address of the dynamic link module name. The maximum length is 9 bytes (including ASCIIZ 
terminator). 

EntryName (PSZ) - input 

Address of the dynamic link entry point name of a routine that receives control when any of the regis- 
tered functions are called. The maximum length is 33 bytes (including ASCIIZ terminator). 

Mask (ULONG) - input 

A mask of bits, where each bit set to 1 identifies a mouse function being registered. Bit values are: 


Bit 

Description 

31-22 

Reserved, set to zero 

21 

MouSetDevStatus 

20 

MouFlushQue 

19 

MoulnitReal 

18 

MouSetPtrPos 

17 

MouGetPtrPos 

16 

MouRemovePtr 

15 

MouDrawPtr 

14 

MouSetPtrShape 

13 

MouGetPtrShape 

12 

MouClose 

11 

MouOpen 

10 

Reserved 

9 

Reserved 

8 

MouSetEventMask 

7 

MouSetScaleFact 

6 

MouGetEventMask 

5 

MouGetScaleFact 

4 

MouReadEventQue 

3 

MouGetNumQueEl 

2 

MouGetDevStatus 

1 

MouGetNumMickeys 

0 

MouGetNumButtons. 


rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

413 ERROR JWOUSEJNVALID_ASCIIZ 

414 ERROR_MOUSE_INVALID~MASK 

415 ERROR_MOUSE_REGISTER 

466 ERROR_MOU_DETACHED 

505 ERROR_MOU_EXTENDED_SG 
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MouRegister - 
Register a Subsystem 


Remarks 

The Base Mouse Subsystem is the default mouse subsystem. There can be only one MouRegister out- 
standing for each session without an intervening MouDeRegister. MouDeRegister must be issued by the 
same process that issued MouRegister. 


When any registered function is called, control is routed to EntryName. When this routine is entered, four 
additional values are pushed onto the stack. The first is the index number (Word) of the function being 
called. The second is a near pointer (Word). The third is the caller's DS register (Word). The fourth is the 
return address (DWord) to the mouse router. For example, if MouGetNumMickeys were called and 
control routed to EntryName, the stack would appear as if the following instructions were executed: 


PUSH? 

WORD 

NumberOfMi ckeys 

PUSH 

WORD 

DeviceHandle 

CALL 

FAR 

MouGetNumMickeys 

PUSH 

WORD 

Function Code 

CALL 

PUSH 

NEAR 

DS 

Entry point in Mouse Router 

CALL 

FAR 

EntryName. 


When a registered function returns to the Mouse Router, AX is interpreted as follows: 
AX = 0 

No error. Do not invoke the Base Mouse Subsystem routine. Return AX = 0. 


AX = —1 

Invoke the BaseMouse Subsystem routine. Return AX = return code from the Base Mouse Sub- 
system. 

AX = error (if not 0 or —1) 

Do not invoke the Base Mouse Subsystem Routine. Return AX = error. 

When the mouse router receives a mouse call, it routes it to the Base Mouse Subsystem unless an appli- 
cation or other mouse sybsystem has previously issued MouRegister for that call. If the call was regis- 
tered, the subsystem is entered at the EntryName specified, and provided with the applicable function 
code. 


The registered function mask is used to determine whether a requested function is performed by the reg- 
istered mouse subsystem or default to the Base Mouse Subsystem. 


The following list shows the relationship of the mouse API calls and the Function Code passed to either 
the Base Mouse Subsystem or a registered mouse subsystem. 


MOU API calls Function Code 

MouGetNumButtons 00H 
MouGetNumMickeys 01 H 
MouGetDevStatus 02H 
MouGetNumQueEl 03H 
MouReadEventQue 03H 
MouGetScaleFact OSH 
MouGetEventMask 06H 
MouSetScaleFact 07H 
MouSetEventMask 08H 
Reserved 09H 

Reserved OAH 

MouOpen OBH 

MouClose OCH 

MouGetPtrShape ODH 
MouSetPtrShape OEH 
MouDrawPtr OFH 

MouRemovePtr 10H 
MouGetPtrPos 11H 

MouSetPtrPos 12H 

MoulnitReal 13H 
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MouFlushQue 14H 

MouSetDevStatus 1 5H 

A registered mouse sybsystem must leave the stack, on exit, in the exact state it was received. 

C Language 

Idefine INCLJtOU 

USHORT rc * MouRegister (ModuleName, EntryName, Mask); 

PSZ ModuleName; /* Module Name */ 

PSZ EntryName; /* Entry Name */ 

ULONG Mask; /* Function Mask */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN MouRegister: FAR 
INCL_M0U EQU 1 

PUSH® ASCI IZ ModuleName ;Module Name 

PUSH® ASCI IZ EntryName ;Entry Name 

PUSH DWORD Mask function Mask 

CALL MouRegister 

Returns WORD 
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MouRemovePtr - 
Remove Mouse Pointer 


This call allows a process to notify the mouse device driver that the area defined by the passed parame- 
ters is for the exclusive use of the application. This area is defined as the collision area and is not avail- 
able to the mouse device driver when drawing pointer images. 


MouRemovePtr (PtrArea, DeviceHandle) 


Parameters 

PtrArea (PNOPTRRECT) - input 

Address of the pointer shape collision area structure: 

leftrow (USHORT) 

Upper left row coordinate (pels or characters), 
leftcol (USHORT) 

Upper left column coordinate (pels or characters), 
rightrow ( USHORT) 

Lower right row coordinate (pels or characters), 
rightcol (USHORT) 

Lower right column coordinate (pels or characters). 

DeviceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

385 ERROR.MOUSE.NO.DEVICE 

387 ERR0RJ40USE.INV.PARMS 

466 ERROR.MOU.DET ACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU.EXTENDED.SG 

Remarks 

MouRemovePtr may be issued by any process in the session. However, only one collision area is active 
at a time. Each MouRemovePtr command has the effect of resetting the collision area to the location and 
area specified by the current command. 

If the logical pointer position is outside of the collision area specified by the latest MouRemovePtr 
command, the pointer image is drawn. 

The MouDrawPtr command effectively cancels the MouRemovePtr command and allows the pointer to be 
drawn anywhere on the screen, until a new MouRemovePtr command is issued. 
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Remove Mouse Pointer 
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C Language 

typedef struct _NOPTRRECT { /* mourt */ 

USHORT row; /* upper left row coordinates */ 

USHORT col; /* upper left column coordinates */ 

USHORT cRow; 

USHORT cCol ; 

} NOPTRRECT ; 

#define INCL_M0U 

USHORT rc - MouRemovePtr (PtrArea, DeviceHandle) ; 

PNOPTRRECT PtrArea; /* Address of pointer data block */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /it return code it/ 

Assembler Language 

NOPTRRECT struc 

mourt_row dw ? ; upper left row coordinates 
mourt_col dw ? ;upper left column coordinates 
mourt_cRow dw ? 
mourt cCol dw ? 

NOPTRRECT ends 

EXTRN MouRemovePtr; FAR 
INCL_M0U EQU 1 

PUSH® OTHER PtrArea ; Address of pointer data block 

PUSH WORD DeviceHandle ; Mouse device handle 

CALL MouRemovePtr 

Returns WORD 
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MouSetDevStatus - 
Set Mouse Device Status 


This call sets the mouse device driver status flags for the installed mouse device driver. 

MouSetDevStatus (DeviceStatus, DeviceHandle) 

Parameters 

DeviceStatus (PUSHORT) - input 

Address of the desired status flag settings. 

The passed parameter is a 2-byte set of flags. Only the high-order byte has meaning. 

Bit Description 

15-10 Reserved, set to zero. 

9 Set if mouse device is to return data in mickeys. 

8 Set if the drawing operations for the pointer draw routine are to be disabled. 

7-0 Reserved, set to zero. 

DeviceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

387 ERROR_MOUSE_INV_PARMS 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

MouSetDevStatus is the complement to MouGetDevStatus. However, not all status flags may be set with 
MouSetDevStatus. Only the flags corresponding to the following functions may be modified: 

• Return data in mickeys. 

Normally, mouse data is returned to the application with the absolute display mode coordinates of 
the pointer image position on the display screen. By setting this status flag, mouse data is returned 
in relative mickeys, a unit of mouse movement. 

• Don’t call pointer draw device. 

Normally, the pointer draw device driver is called for all drawing operations. By setting this status 
flag, the mouse device driver does not call the pointer draw device driver. The application must 
draw any required pointer image on the screen. 

C Language 

Idefine INCL_M0U 

USHORT rc = MouSetDevStatus (DeviceStatus, DeviceHandle); 

PUSHORT DeviceStatus; /* Status flags */ 

HMOU DeviceHandle; lie Mouse device handle */ 

USHORT rc; lie return code */ 
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Set Mouse Device Status 
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Assembler Language 

EXTRN MouSetDevStatus: FAR 
INCL_M0U EQU 1 

PUSH@ WORD DevIceStatus ; Status flags 

PUSH WORD DeviceHandle ; Mouse device handle 

CALL MouSetDevStatus 

Returns WORD 
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MouSetEventMask - 
Set Mouse Event Mask 


This call assigns a new event mask to the current mouse device driver. 


MouSetEventMask (EventMask, DevfceHandle) 

Parameters 

EventMask (PUSHORT) - input 

Address of a value in application storage used to indicate what mouse events are to be placed on the 
event queue (see MouReadEventQue) and which events are to be ignored. 

The EventMask bit values are described below: 

Bit Description 

15-7 Reserved, set to zero. 

6 Set to report button 3 press/release events, without mouse motion 

5 Set to report button 3 press/release events, with mouse motion 

4 Set to report button 2 press/release events, without mouse motion 

3 Set to report button 2 press/release events, with mouse motion 

2 Set to report button 1 press/release events, without mouse motion 

1 Set to report button 1 press/release events, with mouse motion 

0 Set to mouse motion events with no button press/release events. 

A bit clear setting (set to zero) in an EventMask bit position indicates that the associated type of 
event is not reported to the application. Note also that the mouse buttons are always numbered from 
left to right. When the mouse is properly positioned for use, the left-hand button is button 1. 

DevfceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSE_NO_DEVICE 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 E R RO R_M OU_EXTE N DE D_SG 

Remarks 

Setting a bit in the event mask means that the associated event is reported on the mouse FIFO event 
queue. See "MouReadEventQue - Read Mouse Event Queue" on page 4-23 for examples of event 
mask use. 

C Language 

#define INCL_M0U 

USHORT rc - MouSetEventMask (EventMask, DeviceHandle); 

PUSHORT EventMask; /* Mouse device event mask ptr */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 
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Set Mouse Event Mask 
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Assembler Language 

EXTRN MouSetEventMask: FAR 
INCL_M0U EQU 1 

PUSH? WORD EventMask ; Mouse device event mask ptr 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouSetEventMask 

Returns WORD 
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MouSetPtrPos - 
Set Mouse Pointer Position 


This call directs the mouse driver to set a new row and column coordinate position for the mouse pointer. 


MouSetPtrPos (PtrPos, DeviceHandle) 


Parameters 

PtrPos (PPTRLOC) - input 

Address of the mouse pointer position structure: 

pointer row ( USHORT) 

New pointer row coordinate (pels or characters), 
pointercol ( USHORT) 

New pointer column coordinate (pels or characters). 

DeviceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

385 ERROR_MOUSEJMO_DEVICE 

387 ERROR_MOUSE_INV_PARMS 

466 ERROR_MOU_DET ACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

The application must ensure that the coordinate position specified conforms to the current display mode 
orientation for the session. Pel values must be used for graphics modes and character values for text 
modes. 

This function has no effect on the displays current collision area definition as specified by the 
MouDrawPtr call, if the mouse pointer image is directed into a defined collision area, the pointer image 
is not drawn until either the pointer is moved outside the collision area or the collision area is released 
by the MouDrawPtr call. 

C Language 

typedef struct _PTRL0C { 

USHORT row; 

USHORT col ; 

} PTRLOC; 

#define INCL_M0U 

USHORT rc = MouSetPtrPos (PtrPos, DeviceHandle); 

PPTRLOC PtrPos; /* Double word structure */ 

HMOU DeviceHandle; /* Mouse device handle */ 

USHORT rc; /* return code */ 


/* tnoupl */ 

/* pointer row coordinate screen 
position */ 

/* pointer column coordinate screen 
position */ 
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MouSetPtrPos - * PM 

Set Mouse Pointer Position 


Assembler Language 

PTRLOC struc 

moupljrow dw ? ; pointer row coordinate screen position 
moupl_col dw ? ;pointer column coordinate screen position 
PTRLOC ends 

EXTRN MouSetPtrPos: FAR 
INCL.MOU EQU 1 

PU$K@ OTHER PtrPos ; Double word structure 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouSetPtrPos 

Returns WORD 
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MouSetPtrShape - 
Set Mouse Pointer Shape 


This call allows a process to set the pointer shape and size to be used as the mouse device driver pointer 
image for all applications in a session. 


MouSetPtrShape (PtrBuffer, PtrDefRec, DeviceHandle) 


Parameters 

PtrBuffer (PBYTE) - input 

Address of a buffer containing the bit image used by the mouse device driver as the pointer shape 
for that session. The buffer consists of AND and XOR pointer masks in a format meaningful to the 
pointer draw device driver. 

For CGA compatible text modes (0, 1, 2, and 3) the following describes the AND and XOR pointer 
mask bit definitions for each character cell of the masks. Bit values are: 


Bit 

Description 

15 

Blinking 

14 — 12 

Background color 

11 

Intensity 

10-8 

Foreground color 

7-0 

Character 


PtrDefRec (PPTRSHAPE) - input 

Address of the structure where the application stores the necessary data for the pointer draw device 
driver to build a row-by-column image for each bit plane for the current display mode. The pointer 
definition record structure follows: 

TotLength ( USHORT) 

The total length of the data necessary for the pointer draw device driver to build a row-by- 
column image for each bit plane for the current display mode. 

For all OS/2 system-supported modes, TotLength is specified in bytes and is equal to: 

Mono & Text Modes For text mode height and width must be 1, so length is always 4. 

TotLength = (height in chars) * (width in chars) * 2 * 2 
= 1 * 1 * 2 * 2 
= 4 

Graphics Mode Width-in-pels must be a multiple of 8. 

TotLength = (height in pels)*(width in pels)*(bits per pel)*2 / 8 

Modes 4 and 5 (320 X 200) 

TotLength = (height) * (width) *2*2/8 

Mode 6 (640 X 200) 

TotLength = (height) * (width) *1*2/8 
Length calculations produce byte boundary buffer sizes. 

col (USHORT) 

Number of columns in the mouse shape. In graphics modes, this field contains the pel width 
(columns) of the mouse shape for the session and must be greater than or equal to 1. In text 
modes, col must equal 1. 

row (USHORT) 

Number of rows in the mouse shape. In graphics modes, this field contains the pel height (rows) 
of the mouse shape for the session and must be greater than or equal to 1. In text modes, row 
must equal 1. 
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MouSetPtrShape - 
Set Mouse Pointer Shape 


xPM 


coloffset ( USHORT) 

This value is returned by the mouse device driver to indicate the relative column offset within 
the pointer image. The value defines the center (hotspot) of the pointer image. This value is a 
signed number that represents either character or pel offset, depending on the display mode. 

rowoffset ( USHORT) 

This value is returned by the mouse device driver to indicate the relative row offset within the 
pointer image. The value defines the center (hotspot) of the pointer image. This value is a 
signed number that represents either character or pel offset, depending on the display mode. 

Programming Note: 

For other custom displays and for the extended modes of the EGA attachment, it is possible to 
set the display to modes that require multiple bit planes. In these cases, the area sized by the 
row and column limits must be repeated for each bit plane supported in that mode. Conse- 
quently, the calling process must supply enough data to allow the mouse device driver to 
draw the pointer shape on all currently supported bit planes in that session. For text modes, 
row and column offset must equal 0. 

DeviceHandle (HMOU) - input 

Contains the handle of the mouse device obtained from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

385 ERROR_MOUSE_NO_DEVICE 

387 ERROR_MOUSEJNV_PARMS 

466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 

505 ERROR_MOU_EXTENDEDSG 

Remarks 

An application passes a data image to the mouse device driver that the mouse driver applies to the 
screen whenever the logical pointer position is not located in the application-defined collision area. The 
application synchronizes use of the screen with the mouse driver by way of MouRemovePtr and 
MouDrawPtr. 

The pointer shape is dependent on the display device driver used to support the display device. OS/2 
supports text and graphics modes. These modes are restricted to modes 0 through 7, depending on the 
display device. Character modes (modes 0, 1, 2, 3, and 7) support the pointer cursor only as a reverse 
block character. This reverse block character has a character height and width equal to 1. 

The pointer shape is mapped by the Pointer Draw Device Driver and determined completely by the appli- 
cation. The height and width may vary from 1 through the pel size of the display screen. For restrictions 
concerning the Pointer Draw Device Driver, see IBM Operating System/2 Version 1.2 I/O Subsystems And 
Device Support Volume 1. 
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xPM 


MouSetPtrShape - 
Set Mouse Pointer Shape 


C Language 

typedef struct PTRSHAPE { /* rnoups */ 

USHORT cb; /* total length necessary to build 

image ief 

USHORT col; fie # of columns in mouse shape ief 

USHORT row; fie number of rows in mouse shape ief 

USHORT col Hot; /* column coordinate of pointer image 

hotspot ief 

USHORT rowHot; fie row coordinate of pointer image 

hotspot ief 

} PTRSHAPE; 

Idefine INCL_M0U 

USHORT rc = MouSetPtrShape (PtrBuffer, PtrDefRec, DeviceHandle) ; 

PBYTE PtrBuffer; fie Pointer shape buffer ief 

PPTRSHAPE PtrDefRec; fie Pointer definition record ief 

HMOU DeviceHandle; fie Mouse device handle ief 

USHORT rc; fie return code ief 

Assembler Language 

PTRSHAPE struc 

moups_cb dw ? ;total length necessary to build image 

moups_col dw ? ;# of columns in mouse shape 

moups_row dw ? ; number of rows in mouse shape 

moupscolHot dw ? ; column coordinate of pointer image hotspot 

moups_rowHot dw ? ;row coordinate of pointer image hotspot 

PTRSHAPE ends 

EXTRN MouSetPtrShape: FAR 
INCL_M0U EQU 1 

PUSH0 OTHER PtrBuffer ; Pointer shape buffer 

PUSHO OTHER PtrDefRec ; Pointer definition record 

PUSH WORD DeviceHandle ;Mouse device handle 

CALL MouSetPtrShape 

Returns WORD 
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MouSetScaleFact - xpm 

Set Mouse Scaling Factor 


This call assigns to the current mouse device driver a new pair of 1-word scaling factors. 


MouSetScaleFact (ScaleStruct, DevfceHandle) 


Parameters 

ScaleStruct (PSCALEFACT) - input 

Address of the control block structure that contains the current row and column coordinate scaling 
factors. The scaling factors must be greater than or equal to 1 and less than or equal to (32K — 1). 

rowscale ( USHORT) 

Row scaling factor. 

colscale (USHORT) 

Column scaling factor. 

DevfceHandle (HMOU) - input 

Handle of the mouse device from a previous MouOpen. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

385 ERROR_MOUSE_NO_DEVICE 

387 ERRORMOUSEJNV^PARMS 

466 ERRORMOUJDETACHED 

501 ERRORMOUSEJMOCONSOLE 

505 ERROR_MOU_EXTENDED_SG 

Remarks 

MouSetScaleFact sets the mickey-to-pixel ratio for mouse motion. The row scale and column scale ratios 
specify a number of mickeys for each 8 pixels. The default value for the row scale is 8 mickeys for each 8 
pixels. The default value for the column scale is 16 mickeys to 8 pixels. 

The number of pixels moved does not have to correspond 1-to-1 with the number of mickeys the mouse 
moves. The scaling factor defines a sensitivity for the mouse that is a ratio of the number of mickeys 
required to move the cursor 8 pixels on the screen. The sensitivity determines at what rate the cursor 
moves on the screen. 

C Language 

typedef struct JJCALEFACT { /* mouse it/ 

USHORT rowScaTe; /* row scaling factor */ 

USHORT col Scale; /* column coordinate scaling factor it/ 

} SCALEFACT; 

#define INCL_M0U 

USHORT rc = MouSetScaleFact (ScaleStruct, DeviceHandle); 

PSCALEFACT ScaleStruct; /it 2-word structure it/ 

HMOU DeviceHandle; /* Mouse device handle it/ 

USHORT rc; /* return code */ 
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xPM 


MouSetScaleFact - 
Set Mouse Scaling Factor 


Assembler Language 

SCALEFACT struc 

mouscjrowScal e dw ? ;row scaling factor 
mouse col Scale dw ? ; column coordinate scaling factor 
SCALEFACT ends 

EXTRN MouSetScaleFact: FAR 
INCL_M0U EQU 1 

PUSH? OTHER ScaleStruct ; 2-word structure 

PUSH WORD DevIceHandle ; Mouse device handle 

CALL MouSetScaleFact 

Returns WORD 
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MouSynch - 

Get Synchronous Access 


xWPM 


This call provides synchronous access for a mouse subsystem to the mouse device driver. 


MouSynch (IOWait) 


Parameters 

lOWait ( USHORT) ~ input 

Wait for access. The flag Word is defined as follows: 

Value Definition 

0 Control immediately returned to requestor. 

1 Requestor waits until mouse device driver is free. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

121 ERROR_SEM_TIMEOUT 

Remarks 

MouSynch blocks all other threads within a session until the semaphore clears (returns from the sub- 
system to the router). To ensure proper synchronization, MouSynch should be issued by a mouse sub- 
system if it intends to access dynamically modifiable shared data for each session or if it intends to issue 
a DosDevlOCtl. MouSynch does not protect globally shared data from threads in other sessions. 

C Language 

Idefine INCL_M0U 
USHORT rc = MouSynch (IOWait) ; 

USHORT IOWait; /* 

USHORT rc; /* 

Assembler Language 

EXTRN MouSynch: FAR 
INCLJWU EQU 1 

PUSH WORD IOWait ; Indicate wait/no wait 

CALL MouSynch 

Returns WORD 


Indicate wait/no wait */ 
return code */ 
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Chapter 5. Video Function Calls 

This chapter reflects the Video API interface of OS/2 only. 

If ERROR_VIO_SEE_ERROR_LOG is returned, further information about the error that occurred can be 
obtained by calling WinGetLast Error. 

Notes: 

1. Calls marked xPM are not supported by Presentation Manager, and must not be used by Presenta- 
tion Manager applications. An error code is returned if any of these calls are issued. 

2. Calls marked xWPM are not windowable and are not supported by Presentation Manager. They can 
be used in OS/2 mode. 

3. Calls marked FAPI are present in the Family API. 

4. Those calls without an icon are: 

• Windowable 

• Presentation Manager 

• Full-screen 

• Not Family API. 
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VioDeRegister - xwpm 

DeRegister Video Subsystem 


This call deregisters a video subsystem previously registered within a session. 


VioDeRegister ( ) 


Parameters 

rc (U SHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

404 ERROR_VIO_DEREGISTER 

430 ERROR_VIO_ILLEGAL_DURING_POPUP 

465 ERROR_VIO_DETACHED 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

VioDeRegister must be issued by the same process that issued the previous VioRegister. After 
VioDeRegister is issued, subsequent video calls are processed by the Base Video Subsystem. 

C Language 

#define INCL_VI0 

USHORT rc = VioDeRegister (VO ID); 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioDeRegister: FAR 
INCLJ/IO EQU 1 

CALL Vi oDeRegi ster 

Returns WORD 
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VioEndPopUp - 

Deallocate Pop-up Display Screen 


This call is issued by the application when it no longer requires the temporary screen obtained through a 
previous VioPopUp call. 

VioEndPopUp (VioHandle) 

Parameters 

VioHandle ( HVIO ) - input 
A reserved word of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

405 ERROR_VIO_NO_POPUP 

436 ERROR_VIO_INVALID_HANDLE 

Remarks 

When the application issues a VioEndPopUp call, all video calls are directed to the application's normal 
video buffer. 

PM Considerations 

An error is returned if issued with a non-zero handle. 

C Language 

Idefine INCLJIO 

USHORT rc = VioEndPopUp(VioHandle) : 

HVIO VioHandle; /* Vio device handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioEndPopUp:FAR 
INCL_VI0 EQU 1 

PUSH WORD VioHandle ;Vio device handle 
CALL VioEndPopUp 

Returns WORD 
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VioGetAnsi - 
Get ANSI Status 


This call returns the current ANSI status On/Off state. 


VioGetAnsi (Indicator, VIoHandle) 


Parameters 

Indicator (PUSHORT) - output 

Address of the current ANSI status. A value of 1 indicates ANSI is active, and a value of 0 indicates 
ANSI is not active. 

VIoHandle ( HVIO ) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

C Language 

Idefine INCLJ/IO 

USHORT rc = VioGetAnsi (Indi cator, VioHandle); 

PUSHORT Indicator; /* On/Off indicator (returned) */ 

HVIO VioHandle; /* Vio handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioGetAnsi: FAR 
INCL_VI0 EQU 1 

PUSH© WORD Indicator ;0n/0ff indicator (returned) 

PUSH WORD VioHandle ; Vio handle 

CALL VioGetAnsi 

Returns WORD 
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VioGetBuf - 
Get Logical Video Buffer 


This call returns the address of the logical video buffer (LVB). 


VioGetBuf (LVBPtr, Length, VioHandle) 


Parameters 

LVBPtr ( PULONG ) - output 

Address of the selector and offset of the logical video buffer. Applications should not assume the 
offset portion of this far address is 0. 

Length ( PUSHORT) - output 

Address of the length buffer in bytes. The length is: number of rows * number of columns * size of 
cell. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

An application using VioGetBuf can prepare a screen in the application's own logical video buffer (LVB) 
offline. When the application is in the foreground, the physical screen buffer is updated from the LVB 
when VioShowBuf is issued. When the application runs in the background, the physical screen buffer is 
updated when the application is switched to the foreground. 

Once VioGetBuf is issued, all VioWrtXX calls issued while the application is running in the foreground are 
written to the physical display buffer and LVB. If a VioGetPhysBuf is subsequently issued, then the 
VioWrtXX calls are only written to the physical display buffer. They are no longer written to the LVB. 

VioGetMode may be used to determine the dimensions of the buffer. 

If VioSetMode is issued following a VioGetBuf call, the size of the logical video buffer is adjusted to corre- 
spond to the new mode. There is one logical video buffer per session (or presentation space if AVIO 
application) that corresponds to the current mode on the current display configuration. 

PM Considerations 

This function returns the address and length of the Advanced VIO presentation space. The presentation 
space may be used to directly manipulate displayed information. 


C Language 

fdefine INCL.V10 

USHORT rc = VioGetBuf (LVBPtr. Length. VioHandle); 


PULONG 

LVBPtr; 

/* Points to LVB */ 

PUSHORT 

Length; 

/* Length of buffer */ 

HVIO 

VioHandle; 

/* VI o handle */ 

USHORT 

rc; 

/* return code */ 
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VioGetBuf - 

Get Logical Video Buffer 


Assembler Language 

EXTRN VioGetBuf: FAR 
INCL_VI0 EQU 1 

PUSH? DWORD LVBPtr ; Points to LVB 

PUSH$ WORD Length ; Length of buffer 

PUSH WORD VioHandle ; Vio handle 

CALL VioGetBuf 

Returns WORD 
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FAPI 


VioGetConfig - 
Get Video Configuration 


This call returns the video display configuration. 


VioGetConfig (ConfigID, ConflgData, VioHandle) 

Parameters 

ConfigID (USHOR T) - input 

Identifies for which display configuration information is being requested: 

Value Definition 

0 Current configuration 

1 Primary configuration 

2 Secondary configuration. 

For OS/2 1.2, when ConfigID = 0, the current configuration is returned rather than the primary con- 
figuration (as was returned in OS/2 1.0 and 1.1). This change makes the OS/2 mode version of 
VioGetConfig match the family API version that has returned the current configuration starting with 
OS/2 1.0. OS/2 1.0 and 1.1 applications that issued VioGetConfig to determine the display configura- 
tion benefit from this change. The application can run on the configuration selected by the operator 
(by issuing the MODE command before invoking the application) rather than switching away from the 
operator selected display. 

ConflgData (PVIOCONFIGINFO) - output 

Address of structure where the display configuration is returned. 

length ( USHORT) 

Input parameter to VioGetConfig. Length specifies the length of the data structure in bytes 
including Length itself. The maximum size structure required in OS/2 1.0 and 1.1 is 10 bytes. 

The maximum size structure required in OS/2 1.2 is variable and can be determined by issuing 
VioGetConfig with Length set to 2. When Length is set to 2 on input, VioGetConfig returns the 
size of the maximum structure required in the Length field on output. When Length is not equal 
to 2 on input, the Length field is modified on output to reflect the actual number of bytes 
returned. That is, if more than the maximum size was specified, the maximum size is returned. 
However, if less than the maximum size is specified, the value returned reflects the number of 
bytes of complete fields returned. 

adaptertype (USHORT) 

Display adapter type. 

Value Definition 

0 Monochrome-compatible 

1 Color Graphics Adapter (CGA) 

2 Enhanced Graphics Adapter (EGA) 

3 VGA or PS/2 Display Adapter 

4- 6 Reserved 

7 IBM Personal System/2 Display Adapter 8514/A. 

Values ranging from 0-4095 are reserved for IBM. 

dlsplaytype (USHORT) 

Display or monitor type. 

Value Definition 

0 Monochrome display 

1 Color display 

2 Enhanced Color Display 

3 PS/2 Monochrome Display 8503 

4 PS/2 Color Displays 8512 and 8513 

5- 8 Reserved 

9 PS/2 Color Display 8514 
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VioGetConfig - 
Get Video Configuration 


FAPI 


10 IBM Plasma Display Panel 

11 Monochrome Displays 8507 and 8604 

12 Reserved 

Values ranging from 0-4095 are reserved for IBM. 
adaptmem (ULONG) 

Amount of memory, in bytes, on the adapter. 

Configuration # ( USHORT) 

Number of the display configuration that this data corresponds to. This is assigned by the video 
subsystem, not the Base Video Handler (BVH). 

VDHVersion (USHORT) 

This field is reserved. 

Flag bits (USHORT) 

Are defined as follows: 

Bit Description 

15-1 Reserved 

0 Power up display configuration. 

Hardware state buffer size (ULONG) 

Size of the buffer required by the Base Video Handler (BVH) to save the full hardware state 
excluding the physical display buffer. 

Max buffer size - full save (ULONG) 

Maximum size buffer required by the BVH to save the full physical display buffer. 

Max buffer size - partial save (ULONG) 

Maximum size buffer required by the BVH to save the portion of the physical display buffer that 
is overlaid by a pop-up. 

Offset to emulated adapter types (USHORT) 

Offset within the configuration data structure to the following information describing what other 
display adapters are emulated by this display adapter. 

Number of Data words (USHORT) 

Contains a one word field specifying a count of data words to follow. 

Data word 1 (USHORT) 

Bits set in the data words identify display adapters emulated. Data word 1 has the following 
definition: 

Bit Description 

0 Monochrome/printer adapter 

1 Color graphics adapter 

2 Enhanced graphics adapter 

3 VGA or PS/2 display adapter 

4-6 Reserved 

7 851 4/ A Adapter 

8-15 Reserved. 

Data word 2 (USHORT) 

Reserved. 

Data word N (USHORT) 

Reserved. 

Offset to emulated display types (USHORT) 

Offset within the configuration data structure to the following information describing what other 
displays are emulated by this display. 

Number of Data words (USHORT) 

One word field specifying a count of data words to follow. 
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VioGetConfig — 
Get Video Configuration 


Data word 1 (USHORT) 

Bits set in the data words identify dispiays emulated. Data word 1 has the following 
definition: 


Bit 

0 

1 

2 

3 

4 

5-8 

9 

10 
11 

12-15 


Description 

5151 monochrome display 

5153 color display 

5154 enhanced color display 
8503 monochrome display 
8512 or 8513 color display 
Reserved 

8514 color display 
IBM Plasma Display Panel 
Monochrome Displays 8507 and 8604 
Reserved. 


Data word 2 ( USHORT ) 
Reserved 


Data word N ( USHORT) 

Reserved. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

421 ERROR_VIOJNVAUD_PARMS 

436 ERROR_VIOJNVALID_HANDLE 

438 ERROR_VIO_INVALID_LENGTH 

465 ERROR_VIOJDET ACHED 


Remarks 

The values returned may not be correct if the adapter cannot be properly identified by the Base Video 
Handler (BVH) selected at system installation time. It can also be incorrect if the physical setup does not 
match that indicated by the presence of the adapter or by adapter switches. For example, it is impossible 
to detect the absence of a display on a CGA or the display attached to an EGA, despite the setup 
switches. 
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VioGetConfig - 
Get Video Configuration 


FAPI 


C Language 


typedef struct VIOCONFIGINFO { 

/* vioin */ 

USHORT 

cb ; 

/* Length of this data structure */ 

USHORT 

adapter; 

/* Display adapter type */ 

USHORT 

displ ay; 

/* Displ ay /monitor type */ 

ULONG 

cbMemory; 

/* Amount of memory on the adapter in bytes */ 

USHORT 

Configuration; 


USHORT 

VDHVersion; 


USHORT 

Flags; 


ULONG 

HWBuf f erSi ze ; 


ULONG 

FullSaveSize; 


ULONG 

PartSaveSize; 


USHORT 

EMAdaptersOFF; 

/* Offset to emulated adapter types */ 

USHORT 

EMDisplaysOFF; 

/* Offset to emulated display types */ 


> VIOCONFIGINFO; 

Idefine INCL_VI0 

USHORT rc = VioGetConfig(ConfigID, ConfigData,, VioHandle); 

USHORT ConfigID; /* Configuration ID */ 

PVIOCONFIGINFO ConfigData; /* Configuration data */ 

HVIO VioHandle; /* Vio handle */ 


USHORT rc; 


/* return code */ 


Assembler Language 


VIOCONFIGINFO struc 


vi oi n_cb 

dw 

? 

vioin_adapter 

dw 

? 

vioin_di splay 

dw 

? 

vi oi n jrbMemory 

dd 

? 

vi oi n_Conf i gurati on 

dw 

? 

vioin_VDHVersion 

dw 

? 

vioin^Flags 

dw 

? 

vioin_HWBufferSize 

dd 

? 

vi oi n _Ful 1 SaveSi ze 

dd 

? 

vioin_PartSaveSi ze 

dd 

? 

vioin EMAdaptersOFF 

dw 

? 

vioin EMDisplaysOFF 

dw 

? 


VIOCONFIGINFO ends 


Length of this data structure 
Display adapter type 
Display /monitor type 

Amount of memory on the adapter in bytes 


Offset to emulated adapter types 
Offset to emulated display types 


EXTRN VioGetConfig: FAR 
INCLJ/IO EQU 1 


PUSH 

WORD 

ConfigID 

PUSH? 

OTHER 

ConfigData 

PUSH 

WORD 

VioHandle 

CALL 

VioGetConfig 


; Configuration ID 
Configuration data 
;Vio handle 


Returns WORD 
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VioGetCp - 
Query Video Code Page 


This call allows a process to query the code page currently used to display text data. 


VioGetCp (Reserved, CodePagelD, VIoHandle) 


Parameters 

Reserved ( USHORT) - input 
A reserved word of Os. 

CodePagelD {PUSHORT) - output 

Address of a word in the application’s data area. The current video code page is returned in this 
word. 

VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

436 ERROR.VIOJNVALIDJHANDLE 

465 ERROR_VIO_DETACHED 

468 ERROR_VIO_USER_FONT 

Remarks 

The display code page ID previously set by VioSetCp, or inherited from the requesting process, is 
returned to the caller. 

The code page tag returned is the currently active code page. A value of 0000 indicates that the code 
page in use is the ROM code page provided by the hardware. 

If ERROR_VIO_USER_FONT is returned, it indicates a user font that was previously loaded with VioSetFont 
is the active code page. 

C Language 

Idefine INCL_VI0 

USHORT rc c VioGetCp(Reserved, CodePagelD, VioHandle); 

USHORT Reserved; /* Reserved (must be zero) */ 

PUSHORT CodePagelD; /* Code page ID */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; fit return code it/ 

Assembler Language 

EXTRN VioGetCp; FAR 

INCLJMO EQU 1 

PUSH WORD Reserved ; Reserved (must be zero) 

PUSH@ WORD CodePagelD ;Code page ID 

PUSH WORD VioHandle ; Video handle 

CALL VioGetCp 

Returns WORD 
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VioGetCurPos - 
Get Cursor Position 


FAPI 


This call returns the coordinates of the cursor. 


VioGetCurPos (Row, Column, VioHandle) 


Parameters 

Row (PUSHORT) - output 

Address of the current Row position of the cursor where 0 is the top row. 

Column ( PUSHORT) - output 

Address of the current column position of the cursor where 0 is the leftmost column. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

436 ERROR_VIOJNVALID_HANDLE 

465 ERROR_VIO_DETACHED 

C Language 

#define INCLJ/IO 

USHORT rc s VioGetCurPos (Row, Column, VioHandle); 

PUSHORT Row; /* Row return data */ 

PUSHORT Column; /* Column return data */ 

HVIO VioHandle; /* Vio handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioGetCurPos: FAR 
INCL_VI0 EQU 1 

PUSH0 WORD Row ;Row return data 

PUSH® WORD Column ; Column return data 

PUSH WORD VioHandle ;Vio handle 

CALL VioGetCurPos 

Returns WORD 
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FAPI 


VioGetCurType - 
Get Cursor Type 


This call returns the cursor type. 


VioGetCurType (CursorData, VIoHandle) 


Parameters 

CursorData ( PVIOCURSORINFO ) - output 

Address of the cursor characteristics structure: 

startline ( USHORT) 

Horizontal scan line in the character cell that marks the top line of the cursor. If the character 
cell has n scan lines, 0 is the top scan line of the character cell and (n — 1 ) is the bottom scan 
line. 

endline ( USHORT) 

Horizontal scan line in the character cell that marks the bottom line of the cursor. Scan lines 
within a character cell are numbered as defined in startline. 

cursorwidth ( USHORT) 

Width of the cursor. In text modes, cursorwidth is the number of columns. The maximum 
number supported by the OS/2 base video subsystem is 1. In graphics modes, cursorwidth is 
the number of pels. 

cursorattrib {USHORT) 

A value of —1 denotes a hidden cursor, all other values in text mode denote normal cursor and 
in graphics mode denote color attribute. 

VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

If CursorStartLine and CursorEndLine were originally specified as percentages on VioSetCurType (using 
negative values), the positive values into which they were translated are returned. Refer to 
VioSetCurType for more information on how percentages can be used to set CursorStartLine and 
CursorEndLine independent of the number of scan lines per character ceil. 

Family API Considerations 

In DOS mode, VioGetCurType returns only two values for cursorattrib: 0 = visible cursor, and 
—1 = hidden cursor. 
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Get Cursor Type 

C Language 

typedef struct VIOCURSORINFO 
USHORT yStart; 

USHORT cEnd; 

USHORT cx; 

USHORT attr; 

} VIOCURSORINFO; 

Idefine INCL_VI0 

USHORT rc a VioGetCurType (CursorData, VioHandle); 

PVIOCURSORINFO CursorData; /* Cursor characteristics */ 

HVIO VioHandle; /* Vio handle */ 

USHORT rc; /* return code */ 

Assembler Language 

VIOCURSORINFO struc 
vioci ^yStart dw 7 ; cursor start line 
vioci_cEnd dw ? ; cursor end line 
viocijrx dw ? ; cursor width 

vioci_attr dw ? ;-l»hidden cursor, any other=normal cursor 
VIOCURSORINFO ends 


EXTRN 

VioGetCurType: FAR 


INCL_VI0 

EQU 1 


PUSH® 

OTHER 

CursorData 

;Cursor characteristics 

PUSH 

WORD 

VioHandle 

;Vio handle 

CALL 

VioGetCurType 



Returns WORD 


{ /* vioci */ 

/^cursor start line */ 

/* cursor end line */ 

/* cursor width */ 

/* -l=hidden cursor, any other=normal 
cursor */ 
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VioGetFont - 
Get Font 


This call returns either the font table of the size specified or the font in use. 


VioGetFont (RequestBlock, VioHandle) 


Parameters 

RequestBlock ( PVIOFONTINFO ) - input/output 

Address of the font structure that returns current RAM font or specified ROM or code page font 
depending on the request type: 

length (USHORT) 

Length of structure, including length. 

14 Only valid value. 

reqtype (USHORT) 

Request type: 

Value Definition 

0 Get current RAM font for EGA, VGA, or IBM Personal System/2 Display Adapter. 

1 Get ROM font for CGA, EGA, VGA, or IBM Personal System/2 Display Adapter. 

pelcolumns ( USHORT) 

Pel columns in character cell. 

pel rows (USHORT) 

Pel rows in character cell. 

fonttable (PVOID) 

Address of the requested font table returned in a caller-supplied data area. If the storage area Is 
accessed by way of an address of 0, a system-supplied segment containing the requested font 
table is returned. 

tablelength (USHORT) 

Length, in bytes, of the caller-supplied data area where the font table is returned. 

VioHandle (HVIO) - input 
Reserved word of Os. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

421 ERROR_VIOJNVALID_PARMS 

438 ERROR_VIO_INVALID_LENGTH 

465 ERROR_VIOJDET ACHED 

467 ERROR_VIOJFONT 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

For reqtype = 1, return ROM font, the font size requested must be supported by the display adapter 
installed. The 8x8, 8x14, 9x14, 8x16, or 9x16 character font may be requested for the VGA or PS/2 Display 
Adapters. The 8x8, 8x14, or 9x14 font may be requested for the enhanced graphics adapter. The 8x8 font 
may be requested for the color graphics adapter. 

Note: Although graphics mode support is provided in VioGetFont, this support is not provided by the 
Base Video Handlers provided with OS/2. 

For reqtype = 1, return ROM font, the far address returned is a ROM pointer only for those fonts where 
the font table for the full 256-character set is actually contained in ROM. Otherwise, the far address 
returned is a RAM pointer. Note that for 8x8 on the CGA, the font table for the full 256-character set is 


Chapter 5. Video Function Calls 5-15 
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Get Font 


returned. For 9x14 or 9x16 the font table for the full 256-character set is also returned. Partial fonts are 
not returned. The 9x14 and 9x16 fonts are derived from variations of the 8x14 and 8x16 fonts, respec- 
tively, where the definitions of fonts for those characters that are different, are replaced. 

For VioGetFont specifying reqtype = 1, return ROM font, the font returned is derived from the fonts con- 
tained in the system, EGA, VGA, and PS/2 Display Adapter BIOS data areas as applicable. There is an 
exception for the EGA, VGA and PS/2 Display Adapter when VioSetCp or VioSetFont has been issued. In 
that case, the font of the size requested is returned from the active code page or the list of user fonts 
already set. 

C Language 

typedef struct _VI0F0NTINF0 
USHORT cb; 

USHORT type; 

USHORT cxCell ; 

USHORT cyCell; 

PVOID pbData; 

USHORT cbData; 

} VIOFONTINFO; 

#de fine INCL_VI0 

USHORT rc = VioGetFont (RequestBlock, VioHandle); 

PVIOFONTINFO RequestBlock; /* Request block */ 

HVIO VioHandle; /* Vio handle */ 

USHORT rc; /* return code */ 


Assembler Language 

VIOFONTINFO struc 
vi of i jrb dw 

viofi_type dw 

viofi_cxCell dw 
viofi_cyCell dw 
viofi_pbData dd 
viofi_cbOata dw 
VIOFONTINFO ends 

EXTRN VioGetFont: FAR 
INCL_VI0 EQU 1 

PUSH® OTHER RequestBlock ; Request block 

PUSH WORD VioHandle ;Vio handle 

CALL VioGetFont 

Returns WORD 


? ; length of this structure 
? ; request type 

? ; pel columns in character cell 
? ;pel rows in character cell 
? ’.requested font table (returned) 

? ; length of caller supplied data area (in bytes) 


{ /* viofi */ 

/* length of this structure */ 

/* request type */ 

/* pel columns in character cell */ 

/* pel rows in character cell ief 
fie requested font table (returned) ief 
fie length of caller supplied data area 
(in bytes) ief 
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VioGetMode - 
Get Display Mode 


This call returns the mode of the display. 


VioGetMode (ModeData, VioHandle) 


Parameters 

ModeData (PVIOMODEINFO) - input/output 

Far address of a structure where mode characteristics are returned. 

length ( USHORT) 

Input parameter to VioGetMode. Length specifies the length of the data structure in bytes 
including Length itself. The value specified on input controls the amount of mode data returned. 
The minimum structure size required is 2 bytes, and the maximum structure size required is 34 
bytes. For OS/2 1.2, a length of 2 returns the size of the maximum structure required for all the 
mode data. When length is not equal to 2, the length field is modified on output to reflect the 
actual number of bytes returned. 

type (UCHAR) 

Mode characteristics bit mask: 

Bit Description 

7-4 Reserved 

3 0 = VGA-compatible modes 0 thru 13H 

1 — Native mode 

2 0 = Enable color burst 

1 = Disable color burst 
1 0 = Text mode 

1 = Graphics mode 

0 0 = Monochrome compatible mode 

1 = Other, 
numcolors (UCHAR) 

Number of colors defined as a power of 2. This is equivalent to the number of color bits that 
define the color, for example: 

Value Definition 

0 Monochrome modes 7, 7-h and F. 

1 2 colors 

2 4 colors 

4 16 colors 

8 256 colors 

textcols ( USHORT) 

Number of text columns. 

textrows (USHORT) 

Number of text rows. 

pelcols (USHORT) 

Horizontal resolution, number of pel columns, 
pelrows (USHORT) 

Vertical resolution, number of pel rows. 

Attribute Format (UCHAR) 

Format of the attributes. 
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VioGetMode - 
Get Display Mode 


FAPI xPM 


Number of Attributes (UCHAR) 

Number of attributes in a character cell. 

Buffer Address ( ULONG ) 

32-bit physical address of the physical display buffer for this mode. 

Buffer Length (ULONG) 

Length of the physical display buffer for this mode. 

Full Buffer Size (ULONG) 

Size of the buffer required for a full save of the physical display buffer for this mode. 

Partial Buffer Size (ULONG) 

Size of the buffer required for a partial (pop-up) save of the physical display buffer for this mode. 

Extended Data Area Address (PCH) 

Far address to an extended mode data structure or zero if none. The format of the extended 
mode data structure is determined by the device driver and is unknown to OS/2. 

VIoHandle (HVIO) - input 
Reserved word of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

436 ERROR_VIOJNVALID_HANDLE 

438 ERROR_VIO_INVALIDJ_ENGTH 

465 ERROR_VIO_DETACHED 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

Refer to "VioSetMode — Set Display Mode" on page 5-69 for examples. 

C Language 


typedef struct J/IOMODEINFO { 


USHORT cb; 

/* Length of the entire data structure 

*/ 

UCHAR fbType; 

/* Bit mask of mode being set 

*/ 

UCHAR color; 

/* Number of colors (power of 2) 

*/ 

USHORT col ; 

/if Number of text columns 

*/ 

USHORT row; 

/if Number of text rows 

*/ 

USHORT hres; 

/if Horizontal resolution 

*/ 

USHORT vres; 

/if Vertical resolution 

*/ 

UCHAR frot ID; 

/* Attribute format 

*/ 

UCHAR attrib; 

/* Number of attributes 

*/ 


ULONG buf_addr; 

ULONG buf length; 

ULONG fulTj ength; 

ULONG parti alj ength; 

PCH ext data_addr; 

} VIOMQDEINFO; 

typedef VIOMQDEINFO far *PVI0M0DEINF0; 

Idefine INCL_VI0 

USHORT rc = VioGetMode(McdeData, VIoHandle); 

PVIOMODEINFO ModeData; /* Mode characteristics */ 

HVIO VioHandle; /* Vio handle */ 

USHORT rc; /* return code */ 
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VioGetMode ~ 
Get Display Mode 


Assembler Language 

VIOMODEINFO struc 

viomi_cb dw ? ; Length of the entire data structure 

viomi_fbType db ? ;Bit mask of mode being set 

viomi_color db ? ; Number of colors (power of 2) 

vicmi_col dw ? ;Number of text columns 

viomi_row dw ? ;Number of text rows 

viomijires dw ? ; Horizontal resolution 

vicmi_vres dw ? ; Vertical resolution 

vicmi_fmt_ID db ? ; Attribute format 

vicmi_attrib db ? ; Number of attributes 

viotni_buf_addr dd ? ; 

vicmi _buf_length dd ? ; 

vicmi_ful7jength dd ? ; 

vicmijjartialJength dd ? ; 

viomi ext data addr dd ? ; 

VIOMODEINFO" ends" 

EXTRN VioGetMode: FAR 

INCL_VI0 EQU 1 

PUSH@ OTHER ModeData ;Mode characteristics 

PUSH WORD VioHandle ;Vio handle 

CALL VioGetMode 

Returns WORD 
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VioGetPhysBuf - FAPI xWPM 

Get Physical Display Buffer 


This call gets addressability to the physical display buffer. 


VioGetPhysBuf (DisplayBuf, Reserved) 


Parameters 

DisplayBuf(P V/OPH YSBUF) - input/output 

Address of the data structure that contains the physical display buffer address and length on input 
and returns the selectors used to address the display buffer. 

display bufaddr {PBYTE) 

Address of the 32 bit start address (selector: offset) of the physical display buffer passed as input. 
If displaybuflen is 0, then displaybufaddr is the far address of the PhysBuf Block described 
below. 

displaybuflen ( ULONG ) 

32 bit length of the physical display buffer. If displaybuflen is 0, then displaybufaddr is treated as 
the far address of the PhysBuf Block described below and the Selector List is not present. 

selectors (SEL) 

Selector list. 

Returns the selectors (each of word-length) that address the physical display buffer. The first 
selector returned in the list, addresses the first 64KB of the physical display buffer or 
displaybuflen, whichever is smaller. If displaybuflen is greater than 64KB, the second selector 
addresses the second 64KB. 

The last selector returned in the list, addresses the remainder of the display buffer. The applica- 
tion is responsible for ensuring enough space is reserved for the selector list to accommodate 
the specified buffer length. 

PhysBuf Block (PhysBuf) 

Address of the data structure. The PhysBuf Block is a variable length data structure. The first 
word is the Length of the PhysBuf Block in bytes. The remaining words of the structure are the 
selectors that address the physical video buffer. If Length is specified as 2, the required length 
of the PhysBuf Block is returned in its place. 

PhysBuf Block (USHORT) 

Length of PhysBuf structure in bytes 

selector (SEL) 

First selector 

selector (SEL) 

Next selector 

selector (SEL) 


selector (SEL) 

Last selector 

Reserved (USHORT) - input 
Reserved word of Os. 

rc (USHORT) — return 

Return code descriptions are: 

0 NOJERROR 

350 ERROR_VIO_PTR 

429 ERROR_VIOJN_BG 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

436 ERROR_VIOJNVALIDJHANDLE 
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VioGetPhysBuf - 
Get Physical Display Buffer 


465 ERROR_VIO_DETACHED 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

If dlsplaybuflen = 0, VioGetPhysBuf returns a selector that addresses the physical display buffer corre- 
sponding to the current mode. One selector is returned in Selector List If a VioGetPhysBuf is issued 
after a VioGetBuf, then all VioWrtXX calls will on longer be written to the LVB. They will only be written 
to the physical display buffer. An application uses VioGetPhysBuf to get addressability to the physical 
display buffer. The selector returned by VioGetPhysBuf may be used only when an application program 
is executing in the foreground. When an application wants to access the physical display buffer, the 
application must call VioScrLock. VioScrLock either waits until the program is running in the foreground 
or returns a warning when the program is running in the background. For more information refer to 
“VioScrLock - Lock Screen" on page 5-50 and “VioScrUnLock - Unlock Screen” on page 5-60. 

The buffer range specified for the physical screen buffer must fall between hex 'AOOOO' and 'BFFFF' inclu- 
sive. An application may issue VioGetPhysBuf only when it is running in the foreground. An application 
may issue VioGetPhysBuf more than once. 

C Language 

typedef struct VIGPHYSBUF { 

PBYTE pBuf ; 

ULONG cb; 

SEL asel [1] ; 

} VI OPHYSBUF ; 

#define INCL_VI0 

USHORT rc = VioGetPhysBuf (Structure, Reserved); 

PVIOPHYSBUF Structure; /* Data structure */ 

USHORT Reserved; /* Reserved (must be zero) */ 

USHORT rc; /* return code */ 

Assembler Language 

VIOPHYSBUF Struc 

viopb_pBuf dd ? ; Buffer start address 
viopb_cb dd ? ; buffer length 
viopb asel dw 1 dup (?) ; selector list 
VIOPHYSBUF ends 

EXTRN VioGetPhysBuf: FAR 
INCLJIO EQU 1 

PUSH@ OTHER Structure ;Data structure 

PUSH WORD Reserved Reserved (must be zero) 

CALL VioGetPhysBuf 

Returns WORD 


/* viopb */ 

/* Buffer start address */ 
/* Buffer length */ 

/* Selector list */ 
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Get Video State 


FAPI xWPM 


This call returns the current settings of the palette registers, overscan (border) color, blink/background 
intensity switch, color registers, underline location, or target VioSetMode display configuration. 


VioGetState (RequestBlock, VioHandle) 


Parameters 

RequestBlock (PVOID) - input/output 

Address of the video state structures consisting of six different structures depending on the request 
type: 

Type Definition 

0 Get palette registers 

1 Get overscan (border) color 

2 Get blink/background intensity switch 

3 Get color registers 

4 Reserved 

5 Get the scan line for underlining 

6 Get target VioSetMode display configuration. 

7 Reserved 

The six structures, depending on request type, are: 

VIOPALSTATE 

Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 

length ( USHORT) - input 

Length of structure, including length. 

38 Maximum valid value. 

type ( USHORT) - input 

Request type 0 for palette registers. 

palette ( USHORT) - input 

First palette register in the palette register sequence; must be specified in the range 0 
through 15. The palette registers are returned in sequential order. The number returned is 
based upon length. 

color (USHORT*(length—6)f2) - output 

Color value for each palette register. The maximum number of entries in the color value 
array is 16. 

VIOOVERSCAN 

Applies to CGA, VGA, or IBM Personal System/2 Display Adapter. 

length ( USHORT) - input 

Length of structure, including length. 

6 Only valid value. 

type (USHORT) - input 

Request type 1 for overscan (border) color. 

color ( USHORT) - input 
Color value. 

VIOINTENSITY 

Applies to CGA, EGA, MCGA, VGA, or IBM Personal System/2 Display Adapter. 

length ( USHORT) - input 

Length of structure, including length. 

6 Only valid value. 
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VioGetState - 
Get Video State 


type ( USHORT) - input 

Request type 2 for blink/background intensity switch. 

switch ( USHORT) - output 
Switch set as: 

Value Definition 

0 Blinking foreground colors enabled. 

1 High intensity background colors enabled. 

VIOCOLORREG 

Applies to VGA, or IBM Personal System/2 Display Adapter. 

length (USHORT) — input 

Length of structure, including length. 

12 Length in bytes. 

type (USHORT) - input 

Request type 3 for color registers. 

first color (US HORT) - input 

First color register to get in the color register sequence; must be specified in the range 0 
through 255. The color registers are returned in sequential order. 

number color (USHORT) - input 

Number of color registers to get; must be specified in the range 1 through 256. 
datarea (PCH) - input 

Far address of a data area where the color registers are returned. The size of the data area 
must be three bytes times the number of color registers to get. The format of each entry 
returned is as follows: 

Byte 1 Red value 

Byte 2 Green value 

Byte 3 Blue value 

VIOSETUUNELOC 

Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 

length (USHORT) - input 

Length of structure, including length. 

6 Length in bytes. 

type (USHORT) - input 

Request type 5 to get the scan line for underlining. Underlining is enabled only when the 
foreground color is 1 or 9. 

scanline (USHORT) - output 

The value returned is in the range 0 through 31 and is the scan line minus 1. A value of 32 
means underlining is disabled. 

VIOSETTARGET 

length (USHORT) - input 

Length of structure, including length. 

6 Length in bytes. 

type (USHORT) - input 

Request type 6 to get display configuration selected to be the target of the next VioSetMode. 

select (USHORT) - output 
Configuration: 

Value Definition 

0 Default selection algorithm. See VioSetMode. 

1 Primary 

2 Secondary. 
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Get Video State 


FAPI xWPM 


VIoHandle (HVIO) - input 
Reserved word of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

421 ERROR_VIO_INVALID_PARMS 

436 E R R OR_V 1 0_l N VALI D_H AN DLE 

438 ERROR_yiOJNVALID_LENGTH 

465 ERROR_VIO_DET ACHED 

494 ERROR_VIO_EXTENDED_SG 


Family API Considerations 

Request type = 6, Get Target VioSetMode Display Configuration, and request type = 5, Get Underline 
Location, are not supported in the family API. 
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Get Video State 


C Language 

typedef struct _VIOPALSTATE { 

USHORT cb; /* Length of this structure in bytes */ 

USHORT type; /* Request type=0 get palette registers */ 

USHORT i First; /* First palette register to return */ 

USHORT acolorfl]; /* Color value palette register */ 

}VIOPALSTATE; 

typedef VIOPALSTATE far *PVIOPAL$TATE; 
typedef struct JIOOVERSCAN { 

USHORT cb; /* Length of this structure */ 

USHORT type; /* Request type=l get overscan (border) color */ 

USHORT color; /* Color value */ 

}V I00VERSCAN ; 

typedef VIOOVERSCAN far *PVI00VERSCAN; 
typedef struct _VIOINTENSITY { 

USHORT cb; /* Length of this structure */ 

USHORT type; /* Request type=2 get blink/background 

intensity switch */ 

USHORT fs; /* Value of blink/background switch */ 

}VI0 I NTENS ITY ; 

typedef VIOINTENSITY far *PVIOINTENSITY; 

typedef struct _VI0C0L0RREG { /* viocreg */ 

USHORT cb; 

USHORT type; 

USHORT firstcolorreg; 

USHORT numcolorregs; 

PCH colorregaddr; 

}VIOCOLORREG; 

typedef VIOCOLORREG far *PVI0C0L0RREG; 

typedef struct _VI0SETULINEL0C { /* viouline */ 

USHORT cb; 

USHORT type; 

USHORT scanline; 

}VI0SETULINEL0C; 

typedef VIOSETULINELOC far *PVIOSETULINELOC; 

typedef struct VIOSETTARGET { /* viosett icf 
USHORT cb; 

USHORT type; 

USHORT defaultalgorithm; 

} VIOSETTARGET; 

typedef VIOSETTARGET far *PVIOSETTARGET; 

#define INCL_VI0 

USHORT re = VioGetState(RequestBlock f VioHandle); 

PV0I0 RequestBlock; /★ Request block */ 

HVIO VioHandle; /* Vio handle */ 

USHORT rc; /* return code */ 
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Get Video State 


FAPI xWPM 


Assembler Language 


VIOPALSTATE struc 


viopal_cb 

dw ? 

Length of this structure in bytes 

viopal_type 

dw ? 

Request type s 0 get palette registers 

viopal_i First 

dw ? 

First palette register to return 

viopal acolor dw 1 
VIOPALSTATE ends 

dup (?) 

Color value palette register 

VIOOVERSCAN struc 



vi oos_cb 

dw ? 

Length of this structure 

vi oos_type 

dw ? 

Request type=l get overscan (border) color 

vioos color 

dw ? 

Color value 

VIOOVERSCAN ends 



VIOINTENSITY struc 



vi oi nt_cb 

dw ? 

Length of this structure 

vioint_type 

dw ? 

Request type=2 get blink/background intensity switch 

vioint fs 

dw ? 

; Value of blink/background switch 

VIOINTENSITY ends 



VIOCOLORREG struc 



viocreg_cb 

dw ? 


viocreg_type 

dw ? 


vi ocreg_f i rstcol orreg 

dw ? 


vi ocregjiumcol orregs 

dw ? 


viocreg colorregaddr 
VIOCOLORREG ends 

dd ? 


VIOSETULINELOC struc 



viouline_cb 

dw ? 


viouline^type 

dw ? 


viouline scanline 

dw ? 



VIOSETULINELOC ends 

VIOSETTARGET struc 
viosett_cb dw ? ; 

viosett_type dw ? ; 

viosett defaultalgorithm dw ? ; 

VIOSETTARGET ends 

EXTRN VioGetState: FAR 
INCLJIO EQU 1 

PUSH® OTHER RequestBlock ; Request block 

PUSH WORD VioHandle ;Vio handle 

CALL VioGetState 

Returns WORD 
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VioGlobalReg - 

Globally register a video subsystem 


VioGlobalReg allows a subsystem to receive notification at the completion of VIO calls issued by all appli- 
cations running in full-screen sessions. 


VioGlobalReg (ModuleName, EntryPoInt, FunctionMaskl, FunctlonMask2, 0) 


Parameters 

ModuleName (PSZ) - input 

Address of the ASCIIZ string containing the 1 - 8 character file name of the subsystem. The 
maximum length of the ASCIIZ string is 9 bytes including the terminating byte of zero. The module 
must be a dynamic link library but the name supplied must not include the .DLL extension. 

EntryPoInt (PSZ) - input 

Address of the ASCIIZ name string containing the dynamic link entry point name of the routine in the 
subsystem to receive control when any of the registered functions is called. The maximum length of 
the ASCIIZ string is 33 bytes including the terminating byte of zero. 

FunctionMaskl ( ULONG ) - input 

A bit mask where each bit identifies a video function being registered. The bit definitions are shown 
below. The first word pushed onto the stack contains the high-order 16 bits of the function mask, and 
the second word contains the low-order 16 bits. 


Bit 

Registered Function 

Bit 

Registered Function 

31 

VioPrtScToggle 

15 

VioWrtCharStr 

30 

VioEndPopUp 

14 

VioWrtTTY 

29 

VioPopUp 

13 

VioWrtNCel! 

28 

VioSavRedrawUndo 

12 

VioWrtNAttr 

27 

VioSavRedrawWait 

11 

VioWrtNChar 

26 

VioScrUnLock 

10 

VioReadCellStr 

25 

VioScrLock 

9 

VioReadCharStr 

24 

VioPrtSc 

8 

VioShowBuf 

23 

VioGetAnsi 

7 

VioSetMode 

22 

VioSetAnsi 

6 

VioSetCurType 

21 

VioScrollRt 

5 

VioSetCurPos 

20 

VioScrolILf 

4 

VioGetPhysBuf 

19 

VioScrollDn 

3 

VioGetBuf 

18 

VioScrollUp 

2 

VioGetMode 

17 

VioWrtCellStr 

1 

VioGetCurType 

16 

VioWrtCharStrAtt 

0 

VioGetCurPos 


FunctlonMask2 (ULONG) - input 

A bit mask where each bit identifies a video function being registered. The bit mask has the format 
shown below. The first word pushed onto the stack contains the high order 16 bits of the function 
mask, and the second word contains the low order 16 bits. Unused bits are reserved and must be set 
to zero. 

Bit Registered Function 

31-11 Reserved , m ust be set to zero. 

10 VioDeRegister 

9 VioRegister 

8 VioSetState 

7 VioGetState 

6 VioSetFont 

5 VioGetCp 

4 VioSetCp 

3 VioGetConfig 

2 VioGetFont 
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VioGlobalReg - 

Globally register a video subsystem 


1 VioModeUndo 

0 VioModeWait 

Reserved (LONG) - input 

Reserved and must be zero. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

349 ERROR_VIOJNVALID_MASK 

403 ERROR J/IOJNVALIDASCIIZ 

426 ERROR_VIO_REGISTER 

494 ERROR~VlO_EXTENDED_SG 

Remarks 

Notification of VIO calls issued within the hard error handler and DOS (real mode) sessions is not pro- 
vided. 

When control is routed to EntryPoint, the stack appears as it did after the original VIO call except that four 
additional values have been pushed onto the stack. The first is the index number (WORD) of the routine 
called. The second is a near pointer (WORD). The third is the caller’s DS register (WORD). The fourth is 
the return address (DWORD) to the VIO router. 

For example, if VioSetCurPos were a registered function, the stack would appear as if the following 
instruction sequence were executed if VioSetCurPos were called and control routed to EntryPoint: 


PUSH 

WORD 

Row 

PUSH 

WORD 

Column 

PUSH 

WORD 

VioHandle 

CALL 

FAR 

VioSetCurPos 

PUSH 

WORD 

Index 

CALL 

NEAR 

Entry point in Vio router 

PUSH 

WORD 

Caller's DS 

CALL 

FAR 

Dynamic link entry point 


The index numbers that correspond to the registered functions are listed below: 


0 VioGetPhysBuf 

1 VioGetBuf 

2 VioShowBuf 

3 VioGetCurPos 

4 VioGetCurType 

5 VioGetMode 

6 VioSetCurPos 

7 VioSetCurType 
6 VioSetMode 

9 VioReadCharStr 

10 VioReadCellStr 

11 VioWrtNChar 

12 VioWrtNAttr 

13 VioWrtNCell 

14 VioWrtCharStr 

15 VioWrtCharStr Att 

16 VioWrtCellStr 

17 VioWrtTTY 

18 VioScrollUp 

19 VioScrollDn 

20 VioScrolILf 

21 VioScrolIRt 


22 VioSetAnsi 

23 VioGetAnsi 

24 VioPrtSc 

25 VioScrLock 

26 VioScrllnLock 

27 VioSavRedrawWait 

28 VioSavRedrawUndo 

29 VioPopUp 

30 VioEndPopUp 

31 VioPrtScToggle 

32 VioModeWait 

33 VioModeUndo 

34 VioGetFont 

35 VioGetConfig 

36 VioSetCp 

37 VioGetCp 

38 VioSetFont 

39 VioGetState 

40 VioSetState 

41 VioRegister 

42 VioDeRegister 
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VioGlobalReg - 

Globally register a video subsystem 

On entry to the global subsystem, AX contains the return code that Is returned to the application that 
issued the VIO call. The global subsystem must return with all stack parameters and all general purpose 
registers, including AX, restored to the same values as on entry. 

All VIO functions within a session are serialized on a thread basis. That is, when a global subsystem 
receives control, it can safely assume that it is not called again from the same session until the current 
call has completed. Note, however, that VIO calls across different sessions are not serialized. 

VioGlobalReg may only be issued during system initialization. After system initialization, VioGlobalReg 
returns ERROR_VIO_REGISTER. A globally registered subsystem is active for the life of the system. 

If multiple global subsystems are registered, they are given control in the order that they are registered. 

A globally registered subsystem receives control on VIO calls issued from all full-screen sessions except 
the hard error handler and DOS (real mode) sessions. 

C Language 

Idefine INCL_V10 

USHORT rc « VioG1oba1Reg(ModuleName, EntryPoint, FunctionMaskl, FunctionMask2, 0); 

PSZ ModuleName; /★ Module name ief 

PSZ EntryPoint; /* Entry point name */ 

ULONG FunctionMaskl; /* Function mask 1 */ 

ULONG FunctionMask2; fie Function mask 2 ief 

LONG 0; fie Reserved (must be zero) ief 

USHORT rc; fie return code */ 

Assembler Language 

EXTRN VioGloba1Reg:FAR 
INCLJIO EQU 1 

PUSH® ASCIIZ ModuleName ; Module name 

PUSH0 ASCIIZ EntryPoint ; Entry point name 

PUSH DWORD FunctionMaskl function mask 1 

PUSH DWORD FunctionMask2 ; Function mask 2 

PUSH DWORD 0 Reserved (must be zero) 

CALL VioGlobalReg 

Returns WORD 
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VioModeUndo - 
Restore Mode Undo 


xWPM 


This call allows one thread within a process to cancel a VioModeWait issued by another thread within the 
same process. 


VioModeUndo (Ownerlndic, Kllllndlc, Reserved) 


Parameters 

Ownerlndic ( USHORT) - input 

Indicates whether the thread issuing VioModeUndo wants ownership of VioModeWait to be reserved 
for its process. 

Value Definition 

0 Reserve ownership 

1 Give up ownership. 

Kllllndlc ( USHORT) - input 

Indicates whether the thread (with the outstanding VioModeWait) should be returned an error code or 
be terminated. 

Value Definition 

0 Return error code 

1 Terminate thread. 

Reserved ( USHORT) - input 
Reserved word of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

421 ERROR_VIOJNVALID_PARMS 

422 ERROR_VIO_FUNCTION_OWNED 

427 ERROR_VIO_NO_MODE_THREAD 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

465 ERROR_VIO_DETACHiD 

486 ERROR_VIO_BAD_RESERVE 

494 ERROR_VIO_EXTENDED SG 


Remarks 

VioModeUndo may be issued only by a thread within the process that owns VioModeWait. The thread 
issuing VioModeUndo can either reserve ownership of the VioModeWait function for its process or give 
up ownership. The thread whose VioModeWait is cancelled is optionally terminated. 

C Language 

♦define INCl_VI0 


USHORT rc ■ Vi oModeUndo( Owner Indie, Killlndic, Reserved); 


USHORT 

Ownerlndic; 

/* Ownership indicator */ 

USHORT 

Kill Indie; 

/* Terminate indicator */ 

USHORT 

Reserved; 

/* Reserved (must be zero) */ 

USHORT 

rc; 

/* return code */ 
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VioModeUndo - 
Restore Mode Undo 


Assembler Language 

EXTRN VioModeUndo: FAR 
INCLVIO EQU 1 

PUSH WORD Owner Indie ; Ownership indicator 

PUSH WORD Kill Indie terminate indicator 

PUSH WORD Reserved Reserved (must be zero) 

CALL VioModeUndo 

Returns WORD 
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VioModeWait - 
Restore Mode Wait 


xWPM 


This call allows a graphics mode application to be notified when it must restore its video mode, state, and 
modified display adapter registers. The return from this function call provides the notification. 


VioModeWait (RequestType, Notify Type, Reserved) 


Parameters 

RequestType ( USHORT) - input 

Application request event. RequestType = 0 indicates the application wants to be notified at the end 
of a pop-up to restore its mode. RequestType = 0 is the only event supported by VioModeWait. 

NotifyType ( PUSHORT) - output 

Address of the operation to be performed by the application returning from VioModeWait. NotifyType 
= 0, indicating restore mode, is the only type of notification returned. 

Reserved ( USHORT) - input 


Reserved word of Os. 

(USHORT) - 

return 

Return code descriptions are: 

0 

NO_ERROR 

421 

ERROR_VIOJNVALID_PARMS 

422 

ERROR_yiO_FUNCTION OWNED 

423 

ERROR_VIO_RETURN 

424 

ERROR_SCSJNVALID_FUNCTION 

428 

E R R OR_VI 0 JN OS A VE_R EST OR E_TH D 

430 

ERROR_ViOJLLEGAL_DURING_POPUP 

465 

ERROR_VIO_DETACHED 

494 

ERROR_VIO_EXTENDED SG 


Remarks 

At the completion of an application or hard error pop-up (reference VioPopUp), OS/2 notifies the session 
that was originally interrupted for the pop-up to restore its mode. The return from this function call pro- 
vides that notification. The thread that issued the call must perform the restore and then immediately 
re-issue VioModeWait. 

When an application’s VioModeWait thread is notified, the thread must restore its video mode, state, and 
modified display adapter registers. An application’s VioModeWait thread does not restore the physical 
display buffer. OS/2 saves/restores the physical display buffer over a pop-up. 

Only one process for a session can issue VioModeWait. The first process that issues VioModeWait 
becomes the owner of this function. (Refer to "VioModeUndo - Restore Mode Undo” on page 5-30.) 

An application must issue VioModeWait only if it writes directly to the registers on the display adapter. 
Otherwise, the application can allow OS/2 to perform the required restore by not issuing VioModeWait. 

When an application issues VioModeWait, it is also required to issue VioSavRedrawWait to be notified at 
screen switch time to perform a full save or restore. Reference “VioSavRedrawWait — Screen Save 
Redraw Wait” on page 5-48. Two application threads must be dedicated to performing these operations. 
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VioModeWait - 
Restore Mode Wait 


C Language 

fdefine 1NCL_VI0 

USHORT rc = VioModeWait (RequestType, NotifyType, Reserved); 

USHORT RequestType; /* Request type */ 

PUSHORT NotifyType; /* Notify type (returned) */ 

USHORT Reserved; /* Reserved (must be zero) */ 

USHORT rc; /* return code ic/ 

Assembler Language 

EXTRN VioModeWait: FAR 
INCL.VI0 EQU 1 

PUSH WORD RequestType ; Request type 

PU$H@ WORD NotifyType ; Notify type (returned) 

PUSH WORD Reserved ; Reserved (must be zero) 

CALL VioModeWait 

Returns WORD 
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VioPopUp - 

Allocate a Pop-up Display Screen 


This call is issued by an application process when it requires a temporary screen to display a momentary 
message to the user. 


VioPopUp (Options, VioHandle) 


Parameters 

Options ( PUSHORT) — input 

Address of the bit flags that indicate which options to the application are being selected. 

Bit Description 

15-2 Reserved, set to zero. 

1 0 = Non-transparent operation. The video mode is set to text-mode 3, 3*, 3 + , 7, or 7 + . 

The highest resolution supported by the primary display adapter configured in the 
system is selected. The screen is cleared, and the cursor is positioned in the upper left 
corner of the display. 

1 = Transparent operation. If the video mode of the outgoing foreground session is text 
(mode 2, 3, 7, or one of the * or + variations of these modes), no mode change occurs. 
The screen is not cleared, and the cursor remains in its current position. If transparent 
operation is selected, and if the video mode of the outgoing foreground session is not 
text (or if the outgoing foreground session has a VioSavRedrawWait thread), the pop-up 
request is refused. A unique error code ERROR_VIO_TRANSPARENT_POPUP is returned 
in this case. 

OS/2 is responsible for saving and restoring the physical display buffer of the previous 
foreground session around a pop-up. This is true whether transparent or non- 
transparent operation is selected. 

0 0 = Return with unique error code ERROR_VIO_EXISTING_POPUP if pop-up is not imme- 

diately available. 

1 = Wait if pop-up is not immediately available. 

VioHandle (HVIO) - input 
Reserved words of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

405 ERROR_VIO_NO_POPUP 

406 ERROR_VIO~EXISTING_POPUP 

483 ERROR_VIO_TRANSPARENT_POPUP 

Remarks 

VioPopUp is normally issued by the application when it is running in the background and wishes to imme- 
diately display a message to the user without waiting to become the active foreground session. 

When an application process issues VioPopUp, it should wait for the return from the request, if the 
process allows any of its threads to write to the screen before VioPopUp returns a successful return code, 
the screen output may be directed to the application's normal video buffer rather than to the pop-up 
screen. If the process allows any of its threads to issue keyboard or mouse calls before VioPopUp 
returns a successful return code, the input is directed from the application's normal session. Once the 
process that issued VioPopUp receives a successful return code, video and keyboard calls issued by any 
of the threads in the pop-up process are directed to the pop-up screen. This continues until the process 
issues VioEndPopUp. At that time video and keyboard calls resume being directed to the application's 
normal video buffer. 
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VioPopUp - 

Allocate a Pop-up Display Screen 


There may be only one pop-up in existence at any time. If a process requests a pop-up and a pop-up 
already exists, the process has the choice of waiting for the prior pop-up to complete or receiving an 
immediate return with an error code. The error code indicates that the operation failed due to an existing 
pop-up having captured the screen. 

Video pop-ups provide a mechanism for a background application to notify the operator of an abnormal 
event the operator must take some action. When considering the suitability of using pop-ups in a partic- 
ular situation, the possible disruptive effect of pop-ups to the operator should be considered. If the oper- 
ator were interrupted frequently by pop-ups issued by background applications, the operator would not 
effectively work with the foreground application. 

While a video pop-up is in the foreground, the operator cannot use the hot key to switch to another appli- 
cation or to the shell. Before the operator can switch another application or the shell to the foreground, 
the pop-up application must issue VioEndPopUp. 

While a video pop-up is in effect, all video calls from the previous foreground session are blocked until 
the process that Issued VioPopUp issues VioEndPopUp. 


When VioPopUp is issued, only the process within the session that issued VioPopUp is brought to the 
foreground. Assuming the session was already the foreground session, any video calls issued by other 
processes in that session are blocked until the process that issued VioPopUp issues VioEndPopUp. 


DosExecPgm may not be issued by a process during a pop-up. The following video calls are the only 
calls that may be issued during the pop-up by the process that issued VioPopUp: 


VioEndPopUp 

VioGetConfig 

VioGetCp 

VioGetFont 

VioGetAnsi 

VioGetState 

VioGetCurPos 

VioGetCurType 

VioGetMode 

VioReadCharStr 

VioReadCellStr 

VioScrolIRt 

VioScrollUp 

VioScrollDn 


VioScrolILf 

VioSetCurPos 

VioSetCurType 

VioSetCp 

VIoSetFont 

VioSetState 

VIoWrtNChar 

VioWrtNAttr 

VioWrtNCell 

VioWrtCharStr 

VioWrtCharStrAtt 

VioWrtCellStr 

VioWrtTTY 


Selectors to the physical display buffer that the issuing process obtained on a prior VioGetPhysBuf call 
may not be used during the pop-up. 

When an application registers a replacement for VioPopUp within a session, the registered routine is 
invoked only when that session is in the foreground. If VioPopUp is issued when that session is in the 
background, the OS/2 default routine is invoked. If the application’s session is using a keyboard or 
mouse monitor, the monitor does not intercept data while the pop-up is active. 

PM Considerations 

This function can be used from within a PM application. Kbdxxx, Mouxxx, and Vioxxx calls (with a zero 
handle) are all allowed between VioPopUp and VioEndPopUp, and are directed to the pop-up screen. An 
error is returned if issued with a non-zero handle. 
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VioPopUp - 

Allocate a Pop-up Display Screen 


C Language 

#def1ne INCL_VI0 

USHORT rc = VioPopUp (Options, VioHandle); 

PUSHORT Options; /* Option Flags */ 

HVIO VioHandle; /* Vio handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioPopUp: FAR 
INCLJHO EQU 1 

PUSH@ WORD Options ; Opt ion Flags 

PUSH WORD VioHandle ;Vio handle 

CALL VioPopUp 

Returns WORD 
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VioPrtSc - 
Print Screen 


This call is issued by the Session Manager when the operator presses PrtSc. 


VioPrtSc (VioHandle) 


Parameters 

VioHandle ( HVIO ) - input 
Reserved word of Os. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

402 ERROR_VIO_SMG_ONLY 

436 E R RO R_VI 0_l N VALI D_H A N DLE 

465 ERROR_VIO_DET ACHED 

Remarks 

VioPrtSc supports text modes 0 through 3, and 7. An Alternate Video Subsystem may want to register a 
replacement for VioPrtSc. An advanced video subsystem could set a graphics mode while the mode 
known to the base video subsystem PrtSc routine is text. Then, if the operator presses PrtSc, the printer 
output is unpredictable. VioPrtSc is reserved for use by the session manager. Application programs may 
not issue VioPrtSc. 

Three beeps are generated if a hard error is detected while writing to the printer. 


C Language 

#define INCL_VI0 

USHORT rc = VioPrtSc (VioHandle) ; 


HVIO 

VioHandle; 

/* Vio handle */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN VioPrtSc: FAR 
INCLVIO EQU 1 

PUSH WORD VioHandle ;Vio handle 
CALL VioPrtSc 

Returns WORD 
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VioPrtScToggle - 
Toggle Print Screen 


xWPM 


This call is called by the Session Manager when the operator presses Ctrl and PrtSc. 


VioPrtScToggle (VioHandle) 


Parameters 

VioHandle ( HVIO ) - input 
Reserved word of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

355 ERROR_VIO_MODE 

402 ERROR_VIO_SMG_ONLY 

430 ERROR_VIO_ILLEGAL_DURING_POPUP 

436 ERROR_VIOJNVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

VioPrtScToggle toggles the Ctrl and PrtSc state of the foreground session. When the Ctrl and PrtSc state 
is on, all VioWrtTTY calls from that session are echoed to the print device. 

VioPrtScToggle can only be called by the session manager. If an application issues this call, it receives 
an error code. 

Three beeps are generated if a hard error is detected while writing to the printer. When Ctrl and PrtSc is 
turned off, the operator may have to press the Enter key to cause output spooled while Ctrl and PrtSc was 
active to be printed. This is because the spool files are closed when the next VioWrtTTY is executed in 
the session, such as writing the prompt in response to the Enter key. 


C Language 

Idefine INCLJIO 

USHORT rc ® VioPrtScToggle (VioHandle) ; 


HVIO 

VioHandle; 

/* Vio handle */ 

USHORT 

rc; 

/* return code */ 


Assembler Language 

EXTRN VioPrtScToggle: FAR 
INCLJ/IO EQU 1 

PUSH WORD VioHandle ;Vio handle 
CALL VioPrtScToggle 

Returns WORD 
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VioReadCellStr - 
Read Char/Attr String 


This call reads a string of character-attribute pairs (cells) from the screen, starting at the specified 
location. 


VioReadCellStr (CellStr, Length, Row, Column, VioHandle) 


Parameters 

CellStr (PCH) - output 

Address of the buffer where the cell string is returned. 

Length ( PUSHORT) - input/output 

Address of the buffer length in bytes. Length must take into account that each character-attribute(s) 
entry in the buffer is 2 or 4 bytes. If the length of the buffer is not sufficient, the last entry is not 
complete. 

Row ( USHORT) - input 

Starting row of the field to read, 0 is the top row. 

Column (USHORT) - input 

Starting column of the field to read, 0 is the leftmost column. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO”cOL 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

If a string read comes to the end of the line and is not complete, the string read continues at the begin- 
ning of the next line. If the read comes to the end of the screen and is not complete, the read terminates 
and the length is set to the length of the buffer that was filled. 

PM Considerations 

VioReadCellStr reads a string of character/attributes (or cells) from the Advanced VIO presentation space 
starting at the specified location. 


C Language 

#define INCLJIO 

USHORT rc = VioReadCellStr (CellStr, Length, Row, Column, VioHandle); 


PCH 

CellStr; 

/* Cell string buffer */ 

PUSHORT 

Length; 

/* Length of cell string buffer */ 

USHORT 

Row; 

/* Starting row location */ 

USHORT 

Column; 

/* Starting column location */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 
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VioReadCellStr — FAPI 

Read Char/Attr String 

Assembler Language 

EXTRN VioReadCellStr: FAR 
INCL_VI0 EQU 1 

PUSH® OTHER CellStr ;Cell string buffer 

PUSH® WORD Length ; Length of cell string buffer 

PUSH WORD Row ; Starting row location 

PUSH WORD Column ; Starting column location 

PUSH WORD VioHandle ; Video handle 

CALL VioReadCellStr 

Returns WORD 
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VioReadCharStr - 
Read Character String 


This call reads a string of characters from the display starting at the specified location. 


VioReadCharStr (CharStr, Length, Row, Column, VioHandle) 


Parameters 

CharStr (PCH) - output 

Address of the buffer where the character string is returned. 

Length ( PUSHORT) - input/output 

Address of the buffer length in bytes. 

Row ( USHORT) - input 

Starting row of the field to read, 0 is the top row. 

Column ( USHORT) - input 

Starting column of the field to read, 0 is the leftmost column. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case It must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436 ERROR_VIOJNVALIDJHANDLE 

465 ERRORVIODETACHED 

Remarks 

If a string read comes to the end of the line and is not complete, then the string read continues at the 
beginning of the next line. If the read comes to the end of the screen and is not complete, the read termi- 
nates and the length is set to the number of characters read. 

PM Considerations 

VioReadCharStr reads a character string from the Advanced VIO presentation space starting at the speci- 
fied location. 

C Language 

#define INCL_V10 

USHORT rc - VioReadCharStr (CharStr, Length, Row, Column, VioHandle); 


PCH 

CharStr; 

/* Character buffer ief 

PUSHORT 

Length; 

fie Length of buffer ief 

USHORT 

Row; 

fie Starting row location ief 

USHORT 

Column; 

fie Starting column location ief 

HVIO 

VioHandle; 

fie Video handle */ 

USHORT 

rc; 

fie return code ief 
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VioReadCharStr - 
Read Character String 


FAPI 


Assembler Language 

EXTRN VioReadCharStr: FAR 
INCLJ/IO EQU 1 


PU$H@ OTHER CharStr 

PUSHO WORD Length 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioReadCharStr 


; Character buffer 
; Length of buffer 
; Starting row location 
; Starting column location 
; Video handle 


Returns WORD 
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VioRegister - 
Register Video Subsystem 


This call registers an alternate video subsystem within a session. 


VioRegister (ModuleName, EntryPoint, Function Maskl, 
FunctlonMask2) 


Parameters 

ModuleName ( PSZ ) - input 

Address of the ASCIIZ string containing the 1 -8 character file name of the subsystem. The 
maximum length of the ASCIIZ string is 9 bytes including the terminating byte of zero. The module 
must be a dynamic link library but the name supplied must not include the .DLL extension. 

EntryPoint (PSZ) - input 

Address of the ASCIIZ name string containing the dynamic link entry point name of the routine in the 
subsystem to receive control when any of the registered functions is called. The maximum length of 
the ASCIIZ string is 33 bytes including the terminating byte of zero. 

FunctlonMaskl (ULONG) - input 

A bit mask where each bit identifies a video function being registered. The bit definitions are shown 
below. The first word pushed onto the stack contains the high-order 16 bits of the function mask, and 
the second word contains the low-order 16 bits. 


Bit 

Registered Function 

Bit 

Registered Function 

31 

VioPrtScToggle 

15 

VioWrtCharStr 

30 

VioEndPopUp 

14 

VioWrtTTY 

29 

VioPopUp 

13 

VioWrtNCell 

28 

VioSavRedrawUndo 

12 

VioWrtNAttr 

27 

VioSavRedrawWait 

11 

VioWrtNChar 

26 

VioScrUnLock 

10 

VioReadCellStr 

25 

VioScrLock 

9 

VioReadCharStr 

24 

VioPrtSc 

8 

VioShowBuf 

23 

VioGetAnsi 

7 

VioSetMode 

22 

VioSetAnsi 

6 

VioSetCurType 

21 

VioScrolIRt 

5 

VioSetCurPos 

20 

VioScrolILf 

4 

VioGetPhysBuf 

19 

VioScrollDn 

3 

VioGetBuf 

18 

VioScrollUp 

2 

VioGetMode 

17 

VioWrtCellStr 

1 

VioGetCurType 

16 

VioWrtCharStrAtt 

0 

VioGetCurPos 


Funct!onMask2 (ULONG) - input 

A bit mask where each bit identifies a video function being registered. The bit mask has the format 
shown below. The first word pushed onto the stack contains the high order 16 bits of the function 
mask, and the second word contains the low order 16 bits. Unused bits are reserved and must be set 
to zero. 

Bit Description 

31-9 Reserved, set to zero 

6 VioSetState 

7 VioGetState 

6 VioSetFont 

5 VioGetCp 

4 VioSetCp 

3 VioGetConfig 

2 VioGetFont 

1 VioModeUndo 

0 VioModeWait 
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VioRegister - 
Register Video Subsystem 


xWPM 


rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

349 ERROR_VIOJNVALID_MASK 

403 ERROR_ViOJNVALID_ASCilZ 

426 ERROR_VIO_REGISTER 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

465 ERROR_VIOJDETACHiD 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

An alternate video subsystem must register which video calls it handles. The default OS/2 video sub- 
system is the Base Video Subsystem. 

When any of the registered functions are called, control is routed to EntryPoint. When this routine is 
entered, four additional values (5 words) are pushed onto the stack. 

The first value is the index number (Word) of the routine being called. The second value is a near pointer 
(Word). The third value is the caller’s DS register (Word). The fourth value is the return address (DWord) 
to the VIO router. 

For example, if VioSetCurPos were a registered function, the stack would appear as if the following 
instruction sequence were executed if VioSetCurPos were called and control routed to EntryPoint: 


PUSH 

WORD 

Row 

PUSH 

WORD 

Column 

PUSH 

WORD 

VioHandle 

CALL 

FAR 

VioSetCurPos 

PUSH 

WORD 

Index 

CALL 

NEAR 

Entry point in Vio router 

PUSH 

WORD 

Caller’s DS 

CALL 

FAR 

Dynamic link entry point 


The index numbers that correspond to the registered functions are listed below: 


0 

VioGetPhysBuf 

22 

VioSetAnsi 

1 

VioGetBuf 

23 

VioGetAnsi 

2 

VioShowBuf 

24 

VioPrtSc 

3 

VioGetCurPos 

25 

VioScrLock 

4 

VioGetCurType 

26 

VioScrUnLock 

5 

VioGetMode 

27 

VioSavRedrawWait 

6 

VioSetCurPos 

28 

VioSavRedrawUndo 

7 

VioSetCurType 

29 

VioPopUp 

8 

VioSetMode 

30 

VioEndPopUp 

9 

VioReadCharStr 

31 

VioPrtScToggle 

10 

VioReadCellStr 

32 

VioModeWait 

11 

VioWrtNChar 

33 

VioModeUndo 

12 

VioWrtNAttr 

34 

VioGetFont 

13 

VioWrtNCell 

35 

VioGetConfig 

14 

VioWrtCharStr 

36 

VioSetCp 

15 

VioWrtCharStrAtt 

37 

VioGetCp 

16 

VioWrtCellStr 

38 

VioSetFont 

17 

VioWrtTTY 

39 

VioGetState 

18 

VioScrollUp 

40 

VioSetState 

19 

VioScrollDn 



20 

VioScrolILf 



21 

VioScrolIRt 
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VioRegister - 
Register Video Subsystem 

When a registered function returns to the video router, the return code is interpreted as follows: 

Return code = 0 No error. Do not invoke the corresponding Base Video Subsystem routine. 

Return to caller with Return code = 0. 

Return code = —1 No error. Invoke the corresponding Base Video Subsystem routine. 

Return to caller with Return code = return code from Base Video Sub- 
system. 

Return code = error (not 0 or —1) Do not invoke the corresponding Base Video Subsystem routine. 

Return to caller with Return code = error. 

When an application registers a replacement for VioPopUp within a session, the registered routine is only 
invoked when that session is in the foreground. If VioPopUp is issued when that session is in the back- 
ground, the OS/2 default routine is invoked. 

An alternate video subsystem should be designed so the routines registered do not cause any hard 
errors when they are invoked. Otherwise, a system lockout occurs. Code and data segments of regis- 
tered routines, that might be loaded from diskette, must be preloaded. 

All VIO functions within a session are serialized on a thread basis. That is, when an alternate video sub- 
system receives control, it can safely assume that it is not called again from the same session until the 
current call has completed. 

C Language 

fdefine INCL_VI0 

USHORT rc = VioRegister(ModuleName, EntryPoint, FunctionMaskl, 

FunctionMask2) ; 

PSZ ModuleName; /* Module name */ 

PSZ EntryPoint; /* Entry point name */ 

ULONG FunctionMaskl; /* Function mask 1 */ 

ULONG FunctionMask2; /* Function mask 2 */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioRegister; FAR 
INCLJIO EQU 1 

PUSH® ASCI IZ ModuleName ; Module name 
PUSH® ASCI IZ EntryPoint ;Entry point name 
PUSH DWORD FunctionMaskl ; Function mask 1 
PUSH DWORD FunctionMask2 ; Function mask 2 
CALL VioRegister 

Returns WORD 
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VioSavRedrawUndo - 
Screen Save Redraw Undo 


xWPM 


This call allows one thread within a process to cancel a VioSavRedrawWait issued by another thread 
within the same process. 


VioSavRedrawUndo (Ownerlndic, Killlndic, VfoHandle) 


Parameters 

Ownerlndic ( USHORT) - input 

Indicates whether the thread issuing VioSavRedrawUndo wants ownership of VioSavRedrawWait to 
be reserved for its process. 

Value Definition 

0 Reserve ownership 

1 Give up ownership. 

Killlndic ( USHORT) - input 

Indicates whether the thread with the outstanding VioSavRedrawWait should be returned an error 
code or be terminated. 

Value Definition 

0 Return error code 

1 Terminate thread. 

VIoHandle (HVIO) - input 
Reserved word of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

421 ERROR_VIOJNVALID_PARMS 

422 ERROR_VIO_FUNCTION_OWNED 

428 ERROR_VIO_NO_SAVE_RESTORE_THD 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

465 ERROR_VIO_DETACHED 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

The issuing thread can reserve ownership of VioSavRedrawWait for its process or give it up. The thread 
whose VioSavRedrawWait was cancelled is optionally terminated. VioSavRedrawUndo may be issued 
only by a thread within the same process that owns VioSavRedrawWait. 

C Language 

Idefine INCL.VI0 

USHORT rc a VioSavRedrawUndo(OwnerIndic, Killlndic, VioHandle); 


USHORT 

Ownerlndic; 

/* Ownership indicator */ 

USHORT 

Killlndic; 

/* Terminate indicator */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 


5-46 Control Program Programming Reference 







xWPM 


VioSavRedrawUndo - 
Screen Save Redraw Undo 


Assembler Language 

EXTRN VioSavRedrawUndo: FAR 
INCL.VIO EQU 1 

PUSH WORD Gwnerlndic Ownership indicator 

PUSH WORD Killlndic ;Terrainate indicator 

PUSH WORD VioHandle ; Video handle 

CALL Vi oSavRedrawUndo 

Returns WORD 
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VioSavRedrawWait - 
Screen Save Redraw Wait 


xWPM 


This call notifies a graphics mode application when it must save or redraw its screen image. 


VioSavRedrawWait (SavRedrawIndic, Notify Type, VioHandle) 


Parameters 

SavRedrawIndic ( USHORT) - input 

Indicates which events the application is waiting for: 

Value Definition 

0 The session manager notifies the application for both save and redraw operations. 

1 The session manager notifies the application for redraw operations only. 

NotifyType ( PUSHORT) - output 

Address that specifies the operation to be performed by the application upon return from 
VioSavRedrawWait: 

Value Definition 

0 Save screen image 

1 Restore screen image. 

VioHandle (HVIO) - input 
Reserved word of Os. 

rc ( USHORT) - return 


Return code 

i descriptions are: 

0 

NO_ERROR 

421 

ERROR_VIO_INVALID_PARMS 

422 

ERROR_VIO_FUNCTION_OWNED 

423 

ERROR_VIO_RETURN 

430 

ERROR_VIO_ILLEGAL_DURING POPUP 

436 

ERROR_VIO_INVALID_HANDLE 

465 

ERROR_VIO_DETACHED 

494 

ERROR_VIO_EXTENDED SG 


Remarks 

OS/2 uses VioSavRedrawWait to notify a graphics mode application to save or restore its screen image at 
screen switch time. The application in the outgoing foreground session is notified to perform a save. The 
application in the incoming foreground session is notified to perform a restore. The application must 
perform the action requested and immediately re-issue VioSavRedrawWait. When an application per- 
forms a save, it saves its physical display buffer, video mode, and any other information the application 
needs to completely redraw its screen at restore time. 

Oniy one process per session can issue VioSavRedrawWait. The process that first issues 
VioSavRedrawWait becomes the owner of the function. 

A text mode application must issue VioSavRedrawWait only if the application writes directly to the regis- 
ters on the display adapter. Assuming VioSavRedrawWait is not issued by a text mode application, OS/2 
performs the required saves and restores. 

An application that issues VioSavRedrawWait may also need to issue VioModeWait. This would allow the 
application to be notified when it must restore its mode at the completion of an application or hard error 
pop-up. Refer to “VioModeWait — Restore Mode Wait” on page 5-32 for more information. Two appli- 
cation threads would be required to perform these operations in this case. 

At the time a VioSavRedrawWait thread is notified, the session is in transition to/from the background. 
Although the session’s official status is background, any selector to the physical display buffer previously 
obtained by the VioSavRedrawWait process (through VioGetPhysBuf) is valid at this time. The physical 
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VioSavRed raw Wait - 
Screen Save Redraw Wait 


display buffer must be accessed without issuing VioScrLock. Since the session’s official status is back- 
ground, any thread waits if it issues VioScrLock with the "wait if unsuccessful" option. 

An application containing a VioSavRedrawWait thread should be designed so that the process does not 
cause any hard errors while the VioSavRedrawWait thread is running, otherwise a system lockout may 
occur. 

An application’s VioSavRedrawWait thread may be notified to perform a restore before it is notified to 
perform a save. This happens if the application was running in the background the first time it issued 
VioSavRedrawWait. The return from this function call provides the notification. The thread that issues 
the call performs the save or redraw and then reissues VioSavRedrawWait to wait until its screen image 
must be saved or redrawn again. 

C Language 

Idefine INCLJIO 

USHORT rc = VioSavRedrawWait (SavRedrawIndic, NotifyType, VioHandle); 

USHORT SavRedrawIndic; /* Save/redraw indicator */ 

PUSHORT NotifyType; /* Notify type (returned) */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioSavRedrawWait: FAR 
INCLJflO EQU 1 

PUSH WORD SavRedrawIndic ; Save/redraw indicator 

PUSH@ WORD NotifyType ; Notify type (returned) 

PUSH WORD VioHandle ; Video handle 

CALL Vi oSavRedrawWai t 

Returns WORD 
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VioScrLock 
Lock Screen 


FAPI xWPM 


This call requests ownership of (locks) the physical display buffer. 


VioScrLock (WaitFlag, Status, VioHandle) 


Parameters 

WaitFlag ( USHORT) - input 

Indicates whether the process should block until the screen I/O can take place. 

Value Definition 

0 Return if screen I/O not available 

1 Wait until screen I/O is available. 

Status (PUCHAR) - output 

Address of the Indicator of whether the lock is successful, described below. 

Value Definition 

0 Lock successful 

1 Lock unsuccessful (in the case of no wait). 

Status is returned only when AX = 0. 

Status = 1 may be returned only when WaitFlag = 0. 

VioHandle (HVIO) - input 
Reserved word of Os. 

rc ( USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

366 ERROR_VIO_WAIT_FLAG 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

434 ERROR_VIO_LOCK 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

This function call permits a process to determine if I/O to the physical screen buffer can take place. This 
prevents the process from writing to the physical buffer when the process is in the background. Proc- 
esses must cooperate with the system in coordinating screen accesses. 

Screen switching is disabled while the screen lock is in place. If a screen switch is suspended by a 
screen lock, and if the application holding the lock does not issue VioScrUnLock within a system-defined 
time limit, the screen switch occurs, and the process holding the lock is frozen in the background. A 
process should yield the screen lock as soon as possible to avoid being frozen when running in the back- 
ground. The timeout on the lock does not begin until a screen switch is requested. 

When the screen lock is in effect and another thread in the same or different process (in the same 
session) issues VioScrLock, the second thread receives an error code. VioScrUnLock must be issued by 
a thread within the same process that issued VioScrLock. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restriction applies to VioScrLock when coding in the DOS mode: 

The status always indicates the lock is successful (Return code = 0). 
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fapi xwpm VioScrLock — 

Lock Screen 


C Language 

Idefine INCL.VIO 

USHORT rc * VioScrLock(WaitFlag, Status, VioHandle); 

USHORT Wait Flag; /* Block or not */ 

PUCHAR Status; /* Lock status (returned) */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /* return code */ 


Assembler Language 

EXTRN VioScrLock: FAR 
INCLJHO EQU 1 

PUSH WORD WaitFlag ; Block or not 

PUSH@ BYTE Status ;Lock status (returned) 

PUSH WORD VioHandle ; Video handle 

CALL VioScrLock 

Returns WORD 
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VioScrollDn - 
Scroll Screen Down 


FAPI 


This call scrolls the entire display buffer (or area specified within the display buffer) down. 


VioScrollDn (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle) 


Parameters 

TopRow ( USHORT) - input 
Top row to be scrolled. 

LeftCol (USHORT) - input 
Left column to be scrolled. 

BotRow (USHORT) - input 
Bottom row to be scrolled. 

RightCol (USHORT) - input 
Right column to be scrolled. 

Lines (USHORT) - input 

Number of lines to be inserted at the top of the screen area being scrolled. If 0 is specified, no lines 
are scrolled. 

Cell (PBYTE) - input 

Address of the character-attribute(s) pair (2 or 4 bytes) used as a fill character on inserted lines. 
VioHandle (HVIO) — input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436 ERROR_VIOJNVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

TopRow = 0 and LeftCol = 0 identifies the top left corner of the screen. 

If a value greater than the maximum value is specified for TopRow, LeftCol, BotRow, RightCol, or Lines, 
the maximum value for that parameter is used. 

If TopRow and LeftCol = 0 and if BotRow, RightCol, and Lines = 65535 (or —1 in assembler language), the 
entire screen is filled with the character-attribute pair defined by Cell. 
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C Language 

Idefine INCLJ/IO 

USHORT rc a VioScrollDn (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, 





VioHandle); 

USHORT 


TopRow; 

/* Top row */ 

USHORT 


LeftCol ; 

/★ Left column */ 

USHORT 


BotRow; 

/* Bottom row */ 

USHORT 


RightCol ; 

/* Right column */ 

USHORT 


Lines; 

/* Number of lines */ 

PBYTE 


Cell; 

/* Cell to be written */ 

HVIO 


VioHandle; 

/* Video handle */ 

USHORT 


rc; 

/* return code */ 

Assembler Language 

EXTRN 

VioScrollDn: FAR 


1NCL_VI0 

EQU 1 


PUSH 

WORD 

TopRow 

;Top row 

PUSH 

WORD 

LeftCol 

;Left column 

PUSH 

WORD 

BotRow 

; Bottom row 

PUSH 

WORD 

RightCol 

; Right column 

PUSH 

WORD 

Li nes 

; Number of lines 

PUSH? 

OTHER 

Cell 

; Cel 1 to be written 

PUSH 

WORD 

VioHandle 

; Video handle 

CALL 

VioScrollDn 



Returns WORD 


VioScrollDn - 
Scroll Screen Down 
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VioScrolILf - 
Scroll Screen Left 


FAPI 


This call scrolls the entire display buffer (or area specified within the display buffer) to the left. 


VioScrolILf (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VIoHandle) 


Parameters 

TopRow (USHORT) - input 
Top row to be scrolled. 

LeftCol ( USHORT) - input 
Left column to be scrolled. 

BotRow (USHORT) - input 
Bottom row to be scrolled. 

RightCol ( USHORT) - input 
Right column to be scrolled. 

Lines (USHORT) - input 

Number of columns to be inserted at the right of the screen area being scrolled. If 0 is specified, no 
lines are scrolled. 

Cell (PBYTE) - input 

Address of the character attribute(s) pair (2 or 4 bytes) used as a fill character on inserted columns. 
VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436 ERROR j/IOJNVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

TopRow = 0 and LeftCol = 0 identifies the top left corner of the screen. 

If a value greater than the maximum value is specified for TopRow, LeftCol, BotRow, RightCol, or Lines, 
the maximum value for that parameter is used. 

If TopRow and LeftCol = 0 and if BotRow, RightCol, and Lines = 65535 (or —1 in assembler language), the 
entire screen is filled with the character-attribute pair defined by Cell. 
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FAPI 


C Language 

Idefine INCL_VI0 

USHORT rc = VioScrol ILf (TopRow, Lef tCol , BotRow, RightCol, Lines, Cell, 

VioHandle); 


USHORT 


TopRow; 

/* Top row */ 

USHORT 


Left Col ; 

/* Left column */ 

USHORT 


BotRow; 

/* Bottom row */ 

USHORT 


Ri ghtCol ; 

/* Right column */ 

USHORT 


Lines; 

/* Number of lines */ 

PBYTE 


Cell; 

/* Cell to be written */ 

HVIO 


VioHandle; 

/* Video Handle */ 

USHORT 


rc; 

fie return code ie/ 

Assembler Language 

EXTRN 

VioScrol ILf: FAR 


INCLJIO 

EQU 1 


PUSH 

WORD 

TopRow 

;Top row 

PUSH 

WORD 

Left Col 

; Left column 

PUSH 

WORD 

BotRow 

; Bottom row 

PUSH 

WORD 

RightCol 

; Right column 

PUSH 

WORD 

Li nes 

; Number of lines 

PUSH@ 

OTHER 

Cell 

; Cel 1 to be written 

PUSH 

WORD 

VioHandle 

; Video Handle 

CALL 

VioScrolILf 



Returns WORD 


VioScrolILf - 
Scroll Screen Left 
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VioScrolIRt - ™pi 

Scroll Screen Right 


This call scrolls the entire display buffer (or area specified within the display buffer) to the right. 


VioScrolIRt (TopRow, LeftCol, BotRow, RightCol, Lines, Cell, VioHandle) 


Parameters 

TopRow (USHORT) - input 
Top row to be scrolled. 

LeftCol (USHORT) - input 
Left column to be scrolled. 

BotRow ( USHORT) - input 
Bottom row to be scrolled. 

RightCol (USHORT) - input 
Right column to be scrolled. 

Lines (USHORT) - input 

Number of columns to be inserted at the left of the screen area being scrolled. If 0 is specified, no 
lines are scrolled. 

Cell (PBYTE) - input 

Address of the character attribute(s) pair (2 or 4 bytes) used as a fill character on inserted columns. 
VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) - return 

Return code descriptions are; 

0 NO_ERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436 ERROR_VIO_INVALlD_HANDLE 

465 ERROR_VIO_DET ACHED 

Remarks 

TopRow = 0 and LeftCol = 0 identifies the top left corner of the screen. 

If a value greater than the maximum value is specified for TopRow, LeftCol, BotRow, RightCol, or Lines, 
the maximum value for that parameter is used. 

If TopRow and LeftCol = 0 and if BotRow, RightCol, and Lines = 65535 (or —1 in assembler language), the 
entire screen is filled with the character-attribute pair defined by Cell. 
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VioScrolIRt - 
Scroll Screen Right 


C Language 

f define INCLVIO 

USHORT rc = VioScrolIRt (TopRow, Left Col , BotRow. RightCol, Lines, Cell, 

VioHandle); 


USHORT 

TopRow; 

/* Top row */ 

USHORT 

LeftCol ; 

/* Left column */ 

USHORT 

BotRow; 

/* Bottom row */ 

USHORT 

RightCol ; 

/* Right column */ 

USHORT 

Lines; 

/* Number of lines */ 

PBYTE 

Cell; 

/* Cell to be written */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 

Assembler Language 

EXTRN VioScrolIRt: FAR 


INCLJ/IO 

EQU 1 


PUSH WORD 

TopRow 

;Top row 

PUSH WORD 

LeftCol 

;Left column 

PUSH WORD 

BotRow 

; Bottom row 

PUSH WORD 

Ri ghtCol 

; Right column 

PUSH WORD 

Li nes 

; Number of lines 

PUSH0 OTHER 

Cell 

; Cel 1 to be written 

PUSH WORD 

VioHandle 

; Video handle 

CALL VioScrolIRt 



Returns WORD 
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VioScrollUp - 
Scroll Screen Up 


FAPI 


This call scrolls the entire display buffer (or area specified within the display buffer) up. 


VioScrollUp (TopRow, LeftCol, BotRow, RlghtCol, Lines, Cell, VIoHandle) 


Parameters 

TopRow ( USHORT) - input 
Top row to be scrolled. 

LeftCol (USHORT) - input 
Left column to be scrolled. 

BotRow ( USHORT) - input 
Bottom row to be scrolled. 

RlghtCol (USHORT) - input 
Right column to be scrolled. 

Lines (USHORT) - input 

Number of lines to be inserted at the bottom of the screen area being scrolled. If 0 is specified, no 
lines are scrolled. 

Cell (PBYTE) - input 

Address of the character attribute(s) pair (2 or 4 bytes) used as a fill character on inserted lines. 
VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436 ERROR_VIOJNVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

TopRow = 0 and LeftCol = 0 identifies the top left corner of the screen. 

If a value greater than the maximum value is specified for TopRow, LeftCol, BotRow, RightCol, or Lines, 
the maximum value for that parameter is used. 

If TopRow and LeftCol = 0 and if BotRow, RlghtCol, and Lines = 65535 (or —1 in assembler language), the 
entire screen is filled with the character-attribute pair defined by Cell. 
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VioScrollUp - 
Scroll Screen Up 


C Language 

Idefine INCLJ10 

USHORT rc * VioScrol lUp(TopRow, LeftCol, BotRow, RightCol, Lines, Cell, 

VioHandle) ; 


USHORT 


TopRow; 

/* Top row */ 

USHORT 


LeftCol ; 

/* Left column */ 

USHORT 


BotRow; 

/* Bottom row */ 

USHORT 


RightCol ; 

/* Right column */ 

USHORT 


Lines; 

lie Number of lines */ 

PBYTE 


Cell; 

/ie Fill character */ 

HVIO 


VioHandle; 

/ie Video handle ie/ 

USHORT 


rc; 

/ie return code ie/ 

Assembler Language 

EXTRN 

VioScrollUp: FAR 


INCL_VI0 

EQU 1 


PUSH 

WORD 

TopRow 

;Top row 

PUSH 

WORD 

LeftCol 

;Left column 

PUSH 

WORD 

BotRow 

; Bottom row 

PUSH 

WORD 

RightCol 

; Right column 

PUSH 

WORD 

Lines 

; Number of lines 

PUSH® 

OTHER 

Cell 

;Fi 11 character 

PUSH 

WORD 

VioHandle 

;Video handle 

CALL 

VioScrollUp 



Returns WORD 
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VioScrUnLock - fapi xwpm 

Unlock Screen 


This call releases ownership of (unlocks) the physical display buffer. 


VioScrUnLock (VioHandle) 


Parameters 

VioHandle ( HVIO ) - input 
Reserved word of Os. 

re ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

367 ERROR_VIO_UNLOCK 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

494 ERROR_VIO_EXTENDED_SG 

Remarks 

This call releases the screen lock that is set by VioScrLock. The VioScrUnLock call must be issued by a 
thread in the same process as the thread that issued VioScrLock. 

Family API Considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following 
restriction applies to VioScrUnLock when coding in the DOS mode: 

The status always indicates the unlock is successful (return code = 0). 

C Language 

jdefine INCL_VI0 

USHORT rc = VioScrUnlock(VioHandle); 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioScrUnLock; FAR 
INCl_VI0 EQU 1 

PUSH WORD VioHandle ; Video handle 

CALL VioScrUnLock 

Returns WORD 
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VioSetAnsi - 
Set ANSI On or Off 


This call activates or deactivates ANSI support. 


VioSetAnsi (Indicator, VIoHandle) 

Parameters 

Indicator (USHORT) — input 

Equals 1 to activate ANSI support or 0 to deactivate ANSI. 

VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

421 ERROR_VIOJNVALID_PARMS 

430 error j/iojllegalTduring_popup 

436 ERROR_VIOJNVALID_HANDLE 

465 ERRORVIODETACHED 

Remarks 

For ANSI support, “ON" is the default. 

C Language 

fdefine INCL_VI0 

USHORT rc - VioSetAnsi (Indicator, VioHandle); 

USHORT Indicator; /* On /Off indicator */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /* return code */ 

Assembler Language 

EXTRN VioSetAnsi: FAR 
INCL_VI0 EQU 1 

PUSH WORD Indicator ;0n/0ff indicator 

PUSH WORD VioHandle ; Video handle 

CALL Vi oSetAnsi 

Returns WORD 
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VioSetCp - 
Set Code Page 


This call allows a process to set the code page used to display text data on the screen for the specified 
handle. 


VioSetCp (Reserved, CodePagelD, VioHandle) 


Parameters 

Reserved (USHORT) - input 
Reserved word of Os. 

CodePagelD ( USHORT) - input 

The CodePagelD must be either 0, -1, -2, or have been specified on the CONFIG.SYS CODEPAGE = 
statement. A value of 0000 indicates that the code page is to be set to the default ROM code page 
provided by the hardware. A value of —1 enables the user font codepage if user fonts have previ- 
ously been set with VioSetFont. A value of —2 disables the user font and re-enables the prepared 
system codepage or ROM codepage that was active before the user font was enabled. 

If the code page ID is not 0, —1, —2, or does not match one of the ID’s on the CODEPAGE = state- 
ment, an error results. Refer to IBM Operating System/2 Command Reference for a complete 
description of CODEPAGE. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DET ACHED 

469 ERROR_VIO_BAD_CP 

470 ERR0R\l0lN0_CP 

471 ERROR_VIO_NA_CP 

Remarks 

VioSetCp can be used to enable and disable the user font code page as well as the prepared system code 
pages. If a prepared system code page or the ROM code page is specified, any previously set code page 
is disabled and the specified code page is enabled. 

Specifying the special code page of —1 enables the user font code page if user fonts have previously 
been set. Specifying the special code page of —2 disables the user font code page and re-enables the 
prepared system code page or ROM code page that was active before the user font code page was 
enabled. 

PM Considerations 

Valid CodePagelD values are 0 or one that was specified on the CONFIG.SYS CODEPAGE = statement; 

— t and —2 are not valid for PM. 

This call can be used to set an EBCDIC code page for Advanced VIO. For a full-screen or Vio-windowed 
application, this function causes the displayed characters to be reinterpreted immediately in the new 
code page. For a Presentation Manager application, the characters in the base font are reinterpreted in 
the new code page only when other events cause the characters to be repainted. This function has no 
effect on displayed characters that use a font other than the base font. 
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VioSetCp - 
Set Code Page 


C Language 

# define INCLJ/IO 


USHORT 

rc = 

VioSetCp (Reserved, CodePagelD, VioHandle); 

USHORT 


Reserved; 

/* Reserved (must be zero) */ 

USHORT 


CodePagelD; 

/* CodePage Id */ 

HVIO 


VioHandle; 

/* Video handle */ 

USHORT 


rc; 

/* return code */ 

Assembler Language 

EXTRN 

VioSetCp: FAR 


INCLJ/IO 

EQU 1 


PUSH 

WORD 

Reserved 

; Reserved (must be zero) 

PUSH 

WORD 

CodePagelD 

; CodePage Id 

PUSH 

WORD 

VioHandle 

; Video handle 

CALL 

VioSetCp 



Returns WORD 
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VioSetCurPos - 
Set Cursor Position 


FAPI 


This call sets the cursor’s coordinates on the screen. 


VioSetCurPos (Row, Column, VIoHandle) 


Parameters 

Row ( USHORT) - input 

New cursor row position, 0 is the top row. 

Column (USHORT) - input 

New cursor column position, 0 is the leftmost column. 

VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 


0 

NO_ERROR 

355 

ERROR_VIO_MODE 

358 

ERROR_VIO_ROW 

359 

ERROR_VIO_COL 

436 

ERROR_VIO_INVAUD_HANDLE 

465 

ERROR VIO DETACHED 


C Language 

#define 1NCL.VI0 


USHORT rc - VioSetCurPos (Row, Column, VioHandle); 


USHORT 

USHORT 

HVIO 


Row; 

Column; 

VioHandle; 


/* Row data */ 

/* Column data */ 
/* Video handle */ 


USHORT rc; 


/* return code */ 


Assembler Language 

EXTRN VioSetCurPos; FAR 
INCLJ/IO EQU 1 


PUSH 

WORD 

Row 

PUSH 

WORD 

Col umn 

PUSH 

WORD 

VioHandle 

CALL 

VioSetCurPos 


;Row data 
; Column data 
; Video handle 


Returns WORD 
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FAPI 


VioSetCurType - 
Set Cursor Type 


This call sets the cursor type. 


VioSetCurType (CursorData, VIoHandle) 


Parameters 

CursorData ( PVIOCURSORINFO ) - input 

Address of the cursor characteristics structure: 

startline ( USHORT) 

Horizontal scan line in the character cell that marks the top line of the cursor. If the character 
cell has n scan lines, 0 is the top scan line of the character cell and (n - 1) is the bottom scan 
line. 

end line ( USHORT) 

Horizontal scan line in the character cell that marks the bottom line of the cursor. Scan lines 
within a character cell are numbered as defined in startline. The maximum value allowed is 31. 

cursorwidth (USHORT) 

Width of the cursor. In text modes, cursorwidth is the number of columns. The maximum 
number supported by the OS/2 base video subsystem is 1. In graphics modes, cursorwidth is 
the number of pels. 

A value of 0 specifies the default width. In text modes, this is 1 column. In graphics modes, this 
is the number of pels equivalent to the width of one character. 

cursorattrib ( USHORT) 

A value of —1 denotes a hidden cursor, all other values denote a normal cursor. 

VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

355 ERROR_VIO_MODE 

356 ERROR_VIO_WIDTH 

421 ERROR_VIOJNVALID_PARMS 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

To set CursorStartLine and CursorEndLine independent of the number of scan lines for each character 
cell, you may specify these parameters as percentages. OS/2 then calculates the physical start and end 
scan lines, respectively, by multiplying the percentage specified for the parameter by the total number of 
scan lines in the character cell and rounding to the nearest scan line. Percentages are specified as neg- 
ative values (or 0) in the range 0 through —100. Specifying CursorStartLine = —90 and CursorEndLine = 
-100 requests a cursor that occupies the bottom 10 percent of the character cell. 

PM Considerations 

Set the cursor type. The cursor type consists of the cursor start line, end line, width (assumed 0 — one 
column width) and attribute (normal or hidden). 
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VioSetCurType 
Set Cursor Type 


FAPI 


C Language 

typedef struct .VIOCURSORINFO { /* vioci */ 

USHORT yStart; /^cursor start line */ 

USHORT cEnd; /* cursor end line */ 

USHORT cx; /* cursor width */ 

USHORT attr; /* -l=hidden cursor, any other=normal 

cursor */ 

} VIOCURSORINFO; 

Idefine INCLJ/IO 

USHORT rc = VioSetCurType(CursorData f VioHandle); 

PVIOCURSORINFO CursorData; /* Cursor characteristics */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /* return code */ 

Assembler Language 

VIOCURSORINFO struc 
vioci ^y Start dw ? ; cursor start line 
vioci_cEnd dw ? ; cursor end line 
vioci_cx dw ? ; cursor width 

vioci_attr dw ? ;-l*hidden cursor, any other=normal cursor 
VIOCURSORINFO ends 

EXTRN VioSetCurType: FAR 
INCLJ/IO EQU 1 

PUSH@ OTHER CursorData ; Cursor characteristics 

PUSH WORD VioHandle ; Video handle 

CALL VioSetCurType 

Returns WORD 
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FAPI xWPM 


VioSetFont - 
Set Font 


This call downloads a display font. The font being set must be compatible with the current mode. 


VioSetFont (RequestBlock, VEoHandle) 


Parameters 

RequestBlock ( PVIOFONTINFO ) - input 

Address of the font structure containing the request: 

length ( USHORT) 

Length of structure, including length. 

14 Only valid value. 

reqtype (USHORT) 

Request type: 

Type Definition 

0 Set current RAM font for EGA, VGA, or IBM Personal System/2 Display Adapter. 

pelcolumns (USHORT) 

Pel columns in character cell. 

pelrows (USHORT) 

Pel rows in character cell. 

fonttable (PVOID) 

Address of the data area containing font table to set. 
tablelength (USHORT) 

Length, in bytes, of the caller-supplied data area; must be 256 times the character cell height 
specified in pelrows. 

VioHandie (HVIO) - input 
Reserved word of Os. 

rc (USHORT) - return 


Return code 

> descriptions are: 

0 

NO_ERROR 

355 

ERROR_VIO_MODE 

421 

ERROR_VIO_INVALID_PARMS 

436 

ERROR_VIO_INVALID_HANDLE 

438 

ERROR_VIOJNVALID_LENGTH 

465 

ERROR_VIO_DET ACHED 

467 

ERROR_VIO_FONT 

468 

error!viojjser_font 

494 

ERROR VIO EXTENDED_SG 


Remarks 

VioSetFont is applicable only for the enhanced graphics adapter, VGA or IBM Personal System/2 Display 
Adapter. 

Note: Although graphics mode support is provided in VioSetFont, this support is not provided by the 
Base Video Handlers provided with OS/2. 

When VioSetFont is issued, the current code page is reset. If VIoGetCp is subsequently issued, the error 
code ERROR_VIO_USER_FONT is returned. Return code, ERROR_VIO_USER_FONT represents a warning. 
It indicates that although the font could not be loaded into the adapter using the current mode, the font 
was saved as part of a special user font code page for use with a later VioSetMode. Successfully setting 
a user font sets the special user font code page, just as if a code page of —1 was specified using 
VioSetCp. 
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VioSetFont 
Set Font 


FAPI xWPM 


The user font code page consists of the most recent user font of each size that was set by VioSetFont. 
For example, if two 8x12 fonts and three 8x16 fonts had been set, only two fonts, the most recent of the 
8x12 and 8x16 fonts, would be saved. 

The special code page is used in the same way as those code pages specified on the CODEPAGE = 
statement in CONFIG.SYS. 

C Language 

typedef struct _VIOFONTINFO { /* viofi */ 

USHORT cb; /* length of this structure */ 

USHORT type; /* request type */ 

USHORT cxCell; /* pel columns in character cell */ 

USHORT cyCell; /* pel rows in character cell */ 

PVOID pbData; /* requested font table (returned) */ 

USHORT cbData; /* length of caller supplied data area 

(in bytes) */ 

} VIOFONTINFO; 

Idefine INCL_VI0 

USHORT rc - VioSetFont (RequestBlock, VioHandle); 

PVIOFONTINFO RequestBlock; /* Request block */ 

HVIO VioHandle; /* Video handle ie/ 

USHORT rc; /ie return code ie/ 

Assembler Language 

VIOFONTINFO struc 

viofi_cb dw ? ; length of this structure 

viofi_type dw ? ; request type 

viofi_cxCell dw ? ;pel columns in character cell 

viofi_cyCell dw ? ;pel rows in character cell 

viofi_pbData dd ? requested font table (returned) 

viofi cbData dw ? ; length of caller supplied data area (in bytes) 

VIOFONTINFO ends 

EXTRN VioSetFont: FAR 
INCL.VIO EQU 1 

PUSH® OTHER RequestBlock Request block 
PUSH WORD VioHandle ; Video handle 

CALL VioSetFont 

Returns WORD 
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FAPI xPM 


VioSetMode - 
Set Display Mode 


This call sets the mode of the display. 


VioSetMode (ModeData, VIoHandle) 

Parameters 

ModeData ( PVIOMODEINFO ) - input 

Address of the mode characteristics structure: 

length (USHORT) 

Input parameter to VioSetMode. Length specifies the length of the data structure in bytes 
including Length itself. The minimum structure size required is 3 bytes. OS/2 sets to the first 
mode (in the list of modes supported by this display configuration) with a data structure 
matching the mode data specified. 

type ( UCHAR ) 

Mode characteristics bit mask: 

Bit Description 

7-4 Reserved, set to zero. 

3 0 = VGA-compatible modes 0 thru 13H. 

1 = Native mode. 

2 0 = Enable color burst 

1 = Disable color burst. 

1 0 = Text mode. 

1 = Graphics mode. 

0 0 = Monochrome compatible mode. 

1 = Other. 

numcolors (UCHAR) 

Number of colors defined as a power of 2. This is equivalent to the number of color bits that 
define the color, for example: 

Value Definition 

0 Monochrome modes 7, 7+, and F. 

1 2 colors. 

2 4 colors. 

4 16 colors. 

8 256 colors. 

textcois (USHORT) 

Number of text columns. 

textrows (USHORT) 

Number of text rows. 

pelcols (USHORT) 

Horizontal resolution, number of pel columns, 
peirows (USHORT) 

Vertical resolution, number of pel rows. 

Attribute Format (UCHAR) 

Identifies the format of the attributes. 
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VioSetMode - 
Set Display Mode 


FAPI xPM 


Number of Attributes (UCHAR) 

Identifies the number of attributes in a character cell. 

Buffer Address ( ULONG ) 

32-bit physical address of the physical display buffer for this mode. 

Buffer Length (ULONG) 

Length of the physical display buffer for this mode. 

Full Buffer Size (ULONG) 

Size of the buffer required for a full save of the physical display buffer for this mode. 

Partial Buffer Size (ULONG) 

Size of the buffer required for a partial (pop-up) save of the physical display buffer for this mode. 

Extended Data Area Address (PCH) 

Far address to an extended mode data structure or zero if none. The format of the extended 
mode data structure is determined by the device driver and is unknown to OS/2. 

VIoHandle (HVIO) - input 
Reserved word of Os. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

355 ERROR_VIO_MODE 

430 ERROR_VIO_ILLEGAL_DURING_POPUP 

436 ERROR_VIOJNVALID_HANDLE 

438 ERROR_VIO_INVALIDJ_ENGTH 

465 ERROR_VIO_DETACHED 

467 ERROR_VIO_FONT 

468 ERROR_VIO_USER_FONT 

494 ERROR_VIO_EXTENDED_SG 


Remarks 

VioSetMode initializes the cursor position and type. 

VioSetMode does not clear the screen. To clear the screen, use one of the VioScrolIxx calls. 

The disable color burst bit in the Type field in the VioSetMode data structure is functional only for the 
CGA and VGA. This bit causes the color portion of the video signal to be suppressed, producing a black 
and white mode on composite monitors attached to the CGA. On VGA, the bit causes the color lookup 
table to be loaded with values that produce shades of gray instead of colors, again producing a black and 
white mode. For all other combinations of adapters and displays, the setting of this bit is recorded and 
returned on any subsequent VioGetMode call, but otherwise is ignored. 

For text modes in full-screen sessions, the number of rows on the screen is determined by the availability 
of fonts of the correct size. For any specified mode, the size of the character defined by the font must be 
(Horizontal Resolution)/(Text Columns) dots wide and (Vertical Resolution)/(Text Rows) dots high. For 
example, an 8x8 font would support 39 through 43 text rows if the screen resolution were 640x350. 

If VioSetState request type 6 has been issued previously to select the target display configuration for 
VioSetMode, the mode is set on the display configuration selected. If that display configuration does not 
support the mode specified, an error is returned. 

Assuming no target display configuration for VioSetMode is selected, the mode is set on the primary con- 
figuration. If the primary configuration does not support the mode specified, the mode is set on the sec- 
ondary configuration. 
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FAPI xPM 


VioSetMode - 
Set Display Mode 


The following table shows the VioSetMode parameters required to set all the modes supported by the 
CGA, EGA, VGA, and PS/2 Display Adapters. The modes native to the 8514/A and other advanced video 
adapters are set with the Adapter (programming) Interface to these adapters, not VioSetMode. 

Note: Although graphics mode support is provided in VioSetMode, this support is not provided by the 
Base Video Handlers provided with OS/2. 


Table 5-1 (Page 1 of 2). Display Mode Attributes Supported by Adapters 


BIOS 

Mode 

Type 

Color 

Cols 

Rows 

HRes 

VRes 

Valid Adapter/Display Combinations [Emulated] 

0 

5 

4 

40 

25 

320 

200 

[CGA/CD], CGA/Comp, [EGA/CD], [EGA/ECD], 
VGA/Mono, VGA/Color, VGA/Plasma 

<r 

5 

4 

40 

25 

320 

350 

[EGA/ECD], VGA/Mono, VGA/Color, VGA/Plasma 

0 + 

5 

4 

40 

25 

360 

400 

VGA/Mono, VGA/Color 

0# 

5 

4 

40 

25 

320 

400 

VGA/Mono, VGA/Color, VGA/Plasma 

1 

1 

4 

40 

25 

320 

200 

CGA/CD, CGA/Comp, EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, [VGA/Plasma] 

1* 

1 

4 

40 

25 

320 

350 

EGA/ECD, [VGA/Mono], VGA/Color, [VGA/Plasma] 

1 + 

1 

4 

40 

25 

360 

400 

[VGA/Mono], VGA/Color 

1# 

1 

4 

40 

25 

320 

400 

[VGA/Mono], VGA/Color, [VGA/Plasma] 

2 

5 

4 

80 

25 

640 

200 

[CGA/CD], CGA/Comp, [EGA/CD], [EGA/ECD], 
VGA/Mono, VGA/Color, VGA/Plasma 

2* 

5 

4 

80 

25 

640 

350 

[EGA/ECD], VGA/Mono. VGA/Color, VGA/Plasma 

2 + 

5 

4 

80 

25 

720 

400 

VGA/Mono, VGA/Color 

2# 

5 

4 

80 

25 

640 

400 

VGA/Mono, VGA/Color, VGA/Plasma 

3 

1 

4 

80 

25 

640 

200 

CGA/CD, CGA/Comp, EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, [VGA/Plasma] 

3* 

1 

4 

80 

25 

640 

350 

EGA/ECD, [VGA/Mono], VGA/Color, [VGA/Plasma] 

3 + 

1 

4 

60 

25 

720 

400 

[VGA/Mono], VGA/Color 

3# 

1 

4 

80 

25 

640 

400 

[VGA/Mono], VGA/Color, [VGA/Plasma] 

7 

0 

0 

80 

25 

720 

350 

MPA/MD, EGA/MD. VGA/Mono, VGA/Color 

7 + 

0 

0 

80 

25 

720 

400 

VGA/Mono, VGA/Color 

7# 

0 

0 

80 

25 

640 

400 

VGA/Mono, VGA/Color, VGA/Plasma 

n/a 

0 

0 

80 

25 

640 

350 

VGA/Mono, VGA/Color, VGA/Plasma 

n/a 

1 

4 

80 

30 

720 

480 

[VGA/Mono], VGA/Color 

n/a 

1 

4 

80 

30 

640 

460 

[VGA/Mono], VGA/Color, [VGA/Plasma] 

4 

3 

2 

[40] 

[25] 

320 

200 

CGA/CD, CGA/Comp, EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, [VGA/Plasma] 

5 

7 

2 

[40] 

[25] 

320 

200 

[CGA/CD], CGA/Comp, [EGA/CD], [EGA/ECD], 
VGA/Mono, VGA/Color, VGA/Plasma 

6 

3 

1 

[80] 

[25] 

640 

200 

CGA/CD, CGA/Comp, EGA/CD, EGA/ECD, 
VGA/Mono, VGA/Color, VGA/Plasma 

D 

3 

4 

[40] 

[25] 

320 

200 

EGA/CD, EGA/ECD, [VGA/Mono], VGA/Color, 
[VGA/Plasma] 

E 

3 

4 

[80] 

[25] 

640 

200 

EGA/CD, EGA/ECD, [VGA/Mono], VGA/Color, 
[VGA/Plasma] 

F 

2 

0 

[80] 

[25] 

640 

350 

EGA/MD, VGA/Mono, VGA/Color, VGA/Plasma 

10 

3 

4 

[80] 

[25] 

640 

350 

EGA/ECD, [VGA/Mono], VGA/Color, [VGA/Plasma] 

11 

3 

1 

[80] 

[30] 

640 

480 

VGA/Mono, VGA/Color, VGA/Plasma 

12 

3 

4 

[80] 

[30] 

640 

480 

[VGA/Mono], VGA/Color, [VGA/Plasma] 

13 

3 

8 

[40] 

[25] 

320 

200 

[VGA/Mono], VGA/Color, [VGA/Plasma] 

n/a 

11 

8 

[80] 

[30] 

640 

480 

[8514A/Mono], 8514A/Color 

n/a 

11 

4 

[80] 

[30] 

640 

480 

[8514A/Mono], 8514A/Color 

n/a 

11 

8 

[85] 

[38] 

1024 

768 

[8514A/HMono], 8514A/HColor 
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Set Display Mode 


Table 5-1 (Page 2 of 2). Display Mode Attributes Supported by Adapters 


BIOS 

Mode 

Type 

Color 

Col8 

Rows 

HRes 

VRes 

Valid Adapter/Display Combinations [Emulated] 

n/a 

11 

4 

[85] 

[38] 

1024 

768 

[8514A/HMono], 8514A/HColor 


Display Adapters: 


MPA Monochrome/Printer Adapter 

CGA Color Graphics Adapter 

EGA Enhanced Graphics Adapter 

VGA Video Graphics Array, PS/2 Display Adapter 

851 4 A 8514/A Display Adapter 

Displays: 

MD 5151 Monochrome Display 

CD 5153 Color Display 

ECD 5154 Enhanced Color Display 

Mono 8503 PS/2 Monochrome Display, 8507/8604 Display 

HMono 8507/8604 Display 

Cotor 8512/13 PS/2 Color Display, 8514 Display 

HCotor 8514 Display 

Plasma Plasma Display Panel 

Comp Composite Video Monitor 

Notes: 

1. Types 0, 1, and 5 are text modes; types 2, 3, 7, and 11 are graphics modes. 

2. For BIOS modes 0, 2, 5, the color burst is disabled on the CGA and VGA. 

3. The Personal System/2 Display Adapter 8514/A™1 has advanced function modes, which are supported through the 8514/A display 
adapter interface, not the VIO Subsystem. Refer to the Personal System/2 Display Adapter 851 4/ A Technical Reference for details 
of this support. 


Note: For text modes in full-screen, the number of rows may differ from the mode table due to the avail- 
ability of fonts of the correct size as described above. 

PM Considerations 

Windowable VIO sessions support only 80-column, color text modes. When VioSetMode is called from a 
Windowable VIO session, it only verifies that an 80-column text mode was requested, with Text Rows 
between 1 and 255. The resulting mode, which can be queried using VioGetMode, always has Type = 1, 
Color = 4, Text Columns = 80, Text Rows = requested Text Rows, Horizontal Resolution = 640, and Ver- 
tical Resolution = 16 * (Text Rows). 


1 Trademark of IBM Corporation 
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FAPI xPM 


C Language 


typedef struct J/IOMODEINFO { 


USHORT 

cb; 

/* Length of the entire data structure 

*/ 

UCHAR 

fbType; 

/* Bit mask of mode being set 

*/ 

UCHAR 

color; 

fie Number of colors (power of 2) 

*/ 

USHORT 

col ; 

/* Number of text columns 

*/ 

USHORT 

row; 

/* Number of text rows 

*/ 

USHORT 

hres; 

/* Horizontal resolution 

*/ 

USHORT 

vres; 

/* Vertical resolution 

*/ 

UCHAR 

fmt_ID; 

/* Attribute format 

*/ 

UCHAR 

attrib; 

/* Number of attributes 

*/ 

ULONG 

buf_addr; 



ULONG 

buf ength ; 



ULONG 

fulTj ength; 



ULONG 

partialj ength; 



PCH 

ext data addr; 



} VIOMODEINFO; 




typedef VIOMODEINFO far *PVIOMODEINFO; 

#define INCL.VIO 

USHORT rc » VioSetMode (ModeData, VioHandle); 

PVIOMODEINFO ModeData; /* Mode characteristics */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /* return code */ 

Assembler Language 

VIOMODEINFO struc 
viomi_cb 
viomi_fbType 
vi oral _co lor 
viomijzol 
viomi_row 
vi oral _h res 
viomijrres 
viomi_fmt_ID 
viomi_attrib 
viomi_buf_addr 
viomi_buf_l ength 
viomi_full_length 
vi omi j)arti a1_l ength 
vi omi _ext_data_addr 
VIOMODEINFO ends 

EXTRN VioSetMode: FAR 
INCLJ/IO EQU 1 

PUSH® OTHER ModeData ;Mode characteristics 

PUSH WORD VioHandle ; Video handle 

CALL VioSetMode 

Returns WORD 


dw ? ; Length of the entire data structure 

db ? ;Bit mask of mode being set 

db ? ; Number of colors (power of 2) 

dw ? ; Number of text columns 

dw ? ; Number of text rows 

dw ? ; Horizontal resolution 

dw ? ; Vertical resolution 

db ? attribute format 

db ? ; Number of attributes 

dd ? ; 

dd ? ; 

dd ? ; 

dd ? ; 

dd ? ; 


VioSetMode - 
Set Display Mode 
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VioSetState - 
Set Video State 


FAPI xWPM 


This call performs one of the following functions; set palette registers, sets the overscan (border) color, 
set the blink/background intensity switch, set color registers, set the underline location, or set the target 
VioSetMode display configuration. 


VioSetState (RequestBlock, VIoHandle) 


Parameters 

RequestBlock (PVOID) - input 

Address of the video state structures consisting of six different structures depending on the request 
type: 

Type Definition 

0 Set palette registers 

1 Set overscan (border) color 

2 Set blink/background intensity switch 

3 Set color registers 

4 Reserved 

5 Set underline location 

6 Set target VioSetMode display configuration 

7 Reserved 

The six structures, depending on request type, are: 

VI OPALSTATE 

Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 

length ( USHORT) - input 

Length of structure, including length. 

38 Maximum valid value. 

reqtype ( USHORT) - input 

Request type 0 for palette registers. 

palette ( USHORT) - input 

First palette register in the palette register sequence; must be specified in the range 0 
through 15. The palette registers are returned in sequential order. The number returned is 
based upon length. 

color (USHORT*(length—6)f2) - input 

Color value for each palette register. The maximum number of entries in the color value 
array is 16. 

VIOOVERSCAN 

Applies to CGA, VGA, or IBM Personal System/2 Display Adapter. 

length (USHORT) - input 

Length of structure, including length. 

6 Only valid value. 

reqtype (USHORT) - input 

Request type 1 for overscan (border) color. 

color (USHORT) - input 
Color value. 

VIOINTENSITY 

Applies to CGA, EGA, MCGA, VGA, or IBM Personal System/2 Display Adapter. 

length (USHORT) - input 

Length of structure, including length. 
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FAPI xWPM 


VioSetState - 
Set Video State 


6 Only valid value. 

reqtype ( USHORT) - Input 

Request type 2 for blink/background intensity switch. 

switch ( USHORT) - input 
Switch set as: 

Value Definition 

0 Blinking foreground colors enabled. 

1 High intensity background colors enabled. 

VIOCOLORREG 

Applies to VGA, or IBM Personal System/2 Display Adapter. 

length (USHORT) - input 

Length of structure, including length. 

12 Only valid value. 

type ( USHORT) - input 

Request type 3 for color registers. 

first color (USHORT) - input 

First color register to set in the color register sequence; must be specified in the range 
0 through 255. The color registers are set in sequential order. 

number color (USHORT) - input 

Number of color registers to set; must be specified in the range 1 through 256. 
datarea (PCH) - input 

Far address of a data area containing one three-byte entry for each color register to be 
set. The format of each entry is as follows: 

Byte 1 Red value 

Byte 2 Green value 

Byte 3 Blue value. 

VIOSETUUNELOC 

Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 

length (USHORT) - input 

Length of structure, including length. 

6 Only valid value. 

type (USHORT) - input 

Request type 5 to set the scan line for underlining. Underlining is enabled only when 
the foreground color is 1 or 9. 

scanline (USHORT) - input 

Scan line minus 1. Values of 0 through 31 are acceptable. A value of 32 means under- 
lining is disabled. 

VIOSETTARGET 

length (USHORT) - input 

Length of structure, including length. 

6 Only valid value. 

type (USHORT) - input 

Request type 6 to set display configuration to be the target of the next VioSetMode. 

select (USHORT) - input 
Configuration: 

Value Definition 

0 Default selection algorithm. See VioSetMode. 

1 Primary 

2 Secondary. 
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VioSetState - 
Set Video State 


FAPI xWPM 


VioHandle (HVIO) - input 
Reserved word of Os. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO.ERROR 

355 ERROR_VIO_MODE 

421 ERRORJ/IOJNVALID_PARMS 

436 ERROR_VIO_INVALID_HANDLE 

438 ERROR_VIO_INVALIDJLENGTH 

465 ERROR_VIOJDETACHED 

494 ERROR_VIO_EXTENDED_SG 


Family API Considerations 

Request type = 6, Set Target VioSetMode Display Configuration, and request type = 5, Set Underline 
Location, are not supported in the family API. 
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FAPI xWPM 


VioSetState - 
Set Video State 


C Language 

typedef struct _VIQPALSTATE { 

USHORT cb; /* Length of this structure in bytes */ 

USHORT type; /* Request type=0 get palette registers */ 

USHORT i First; /* First palette register to return */ 

USHORT acolor[l]; /* Color value palette register */ 

}VIOPALSTATE; 

typedef VIOPALSTATE far *PVIOPALSTATE; 
typedef struct JIOOVERSCAN { 

USHORT cb; /* Length of this structure */ 

USHORT type; /* Request type-1 get overscan (border) color */ 

USHORT color; /* Color value */ 

}VI00VERSCAN; 

typedef VIOOVERSCAN far *PVI00VERSCAN; 
typedef struct _VIOINTENSITY { 

USHORT cb; /* Length of this structure */ 

USHORT type; /* Request type=2 get blink/background 

intensity switch */ 

USHORT fs; /* Value of blink/background switch */ 

}VI0I NTENSITY ; 

typedef VIOINTENSITY far *PVIOINTENSITY; 

typedef struct VIOCOLORREG { /* viocreg */ 

USHORT cb; 

USHORT type; 

USHORT firstcolorreg; 

USHORT numcolorregs; 

PCH colorregaddr; 

} VIOCOLORREG; 

typedef VIOCOLORREG far *PVI0C0L0RREG; 

typedef struct _VIOSETULINELOC { /* viculine */ 

USHORT cb; 

USHORT type; 

USHORT scanline; 

JVIOSETULINELOC; 

typedef V10SETULINEL0C far *PVIOSETULINELOC; 

typedef struct J/IOSETTARGET { /* viosett */ 

USHORT cb; 

USHORT type; 

USHORT defaultalgorithm; 

}VIOSETTARGET; 

typedef VIOSETTARGET far *PVIOSETTARGET; 

Idefine INCL_VIO 

USHORT rc = VioSetState(RequestBlock, VioHandle); 

PVOID RequestBlock; fie Request block */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /* return code */ 
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VioSetState - 
Set Video State 


FAPI xWPM 


Assembler Language 


VIOPALSTATE struc 



viopal_cb 

dw ? 

.Length of this structure in bytes 

viopal_type 

dw ? 

.Request type=0 get palette registers 

viopal _i Fi rst 

dw ? 

;First palette register to return 

viopal acolor dw 1 

dup (?) 

Color value palette register 

VIOPALSTATE ends 



VIOOVERSCAN struc 



vioos_cb 

dw ? 

Length of this structure 

vioos_type 

dw ? 

Request type=l get overscan (border) color 

vioos color 

dw ? 

Color value 

VIOOVERSCAN ends 



VIOINTENSITY struc 



vioint_cb 

dw ? 

Length of this structure 

vioint_type 

dw ? 

Request type-2 get blink/background intensity switch 

vioint fs 

dw ? 

Value of blink/background switch 

VIOINTENSITY ends 



VIOCOLORREG struc 



viocregjrb 

dw ? 


viocreg_type 

dw ? 


vi ocreg_f i rstcol orreg 

dw ? 


vi ocregjiumcol orregs 

dw ? 


viocreg colorregaddr 

dd ? 


VIOCOLORREG ends 



VIOSETULINELOC struc 



viouline_cb 

dw ? 


viouline_type 

dw ? 


viouline scanline 

dw ? 


VIOSETULINELOC ends 



VIOSETTARGET struc 



vi osett_cb 

dw ? 

f 

viosett_type 

dw ? 

9 


viosett default algorithm dw ? ; 
VIOSETTARGET ends 

EXTRN VioSetState: FAR 
INCLJ/IO EQU 1 

PUSH@ OTHER RequestBlock ; Request block 
PUSH WORD VioHandle ; Video handle 

CALL VioSetState 

Returns WORD 
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VioShowBuf - 
Display Logical Buffer 


This call updates the physical display buffer with the logical video buffer (LVB). 


VioShowBuf (Offset, Length, VioHandle) 

Parameters 

Offset (USHOR T) - input 

Starting offset within the logical video buffer at which the update to the screen is to start. 

Length ( USHORT) - input 

Length of the area to be updated to the screen. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) — return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

430 ERROR_VIOJLLEGAL_DURING_POPUP 

436 ERROR_VIOJNVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

VioShowBuf is ignored unless it is issued by a process that has previously called VioGetBuf and that Is 
currently executing in the foreground. 

PM Considerations 

This function updates the display with the Advanced VIO presentation space. 

C Language 

f define INCL_VI0 

USHORT rc = VioShowBuf (Offset , Length, VioHandle); 

USHORT Offset; /* Offset into LVB */ 

USHORT Length; /* Length */ 

HVIO VioHandle; /* Video handle */ 

USHORT rc; /is return code */ 

Assembler Language 

EXTRN VioShowBuf; FAR 
INCL_VI0 EQU 1 

PUSH WORD Offset ; Offset into LVB 

PUSH WORD Length ; Length 

PUSH WORD VioHandle ; Video handle 

CALL VioShowBuf 

Returns WORD 
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VioWrtCellStr - 
Write Char/Attr String 


FAPI 


This call writes a string of character-attribute pairs (cells) to the display. 


VioWrtCellStr (CellStr, Length, Row, Column, VioHandle) 


Parameters 

CellStr (PCH) - input 

Address of the string of character-attribute(s) cells to be written. 

Length ( USHORT) - input 

Length, in bytes, of the string to be written. Each character-attribute(s) cell is 2 or 4 bytes. 

Row (USHORT) - input 
Starting cursor row. 

Column ( USHORT) - input 
Starting cursor column. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

re (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERRORVIOMODE 

358 ERROR_VIO_ROW 

359 ERRORVIOCOL 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

If a string write gets to the end of the line and is not complete, the string write continues at the beginning 
of the next line. If the write gets to the end of the screen, the write terminates. 

PM Considerations 

Write a character-attribute string to the Advanced VIO presentation space. The caller must specify the 
starting location on the presentation space where the string is to be written. 

C Language 

Idefine INCIJMO 


USHORT rc = VioWrtCellStr (CellStr, Length, Row, Column, VioHandle); 


PCH 

CellStr; 

/* String to be written */ 

USHORT 

Length; 

/* Length of string */ 

USHORT 

Row; 

/* Starting row position for output */ 

USHORT 

Column; 

/* Starting column position for output */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 
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FAPI 


VioWrtCellStr - 
Write Char/Attr String 


Assembler Language 

EXTRN VioWrtCellStr: FAR 
INCL_VI0 EQU 1 


PUSH® OTHER CellStr 

PUSH WORD Length 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioWrtCellStr 


; String to be written 
; Length of string 
; Starting row position for output 
; Starting column position for output 
; Video handle 


Returns WORD 
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VioWrtCharStr - 
Write Character String 


FAPI 


This call writes a character string to the display. 


VioWrtCharStr (CharStr, Length, Row, Column, VIoHandte) 


Parameters 

CharStr (PCH) - input 

Address of the character string to be written. 

Length ( USHORT) - input 

Length, in bytes, of the character string. 

Row ( USHORT) - input 
Starting cursor row. 

Column (USHORT) - input 
Starting cursor column. 

VioHandle ( HVIO ) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERRORVIOCOL 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

If a string write gets to the end of the line and is not complete, the string write continues at the beginning 
of the next line, if the write gets to the end of the screen, the write terminates. 

PM Considerations 

Write a character string to the Advanced VIO presentation space. The caller must specify the starting 
location on the presentation space where the string is to be written. 


C Language 

Idefine 1NCL_VI0 

USHORT rc = VioWrtCharStr (CharStr, Length, Row, Column, VioHandle); 


PCH 

CharStr; 

/* String to be written */ 

USHORT 

Length; 

/* Length of character string */ 

USHORT 

Row; 

/* Starting row position for output */ 

USHORT 

Column; 

/* Starting column position for output */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 
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FAPI 


VioWrtCharStr - 
Write Character String 


Assembler Language 

EXTRN VioWrtCharStr: FAR 
INCL_VI0 EQU 1 


PUSH@ OTHER CharStr 

PUSH WORD Length 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioWrtCharStr 


; String to be written 
; Length of character string 
; Starting row position for output 
starting column position for output 
; Video handle 


Returns WORD 
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VioWrtCharStrAtt - 
Write Char String with Attr 


FAPI 


This call writes a character string with repeated attribute to the display. 


VioWrtCharStrAtt (CharStr, Length, Row, Column, Attr, VIoHandle) 


Parameters 

CharStr ( PCH ) - input 

Address of the character string to be written. 

Length ( USHORT) - input 

Length, in bytes, of the character string. 

Row (USHORT) - input 
Starting cursor row. 

Column (USHORT) - input 
Starting cursor column. 

Attr (PBYTE) - input 

Address of the attribute(s) (1 or 3 bytes) to be used in the display buffer for each character of the 
string written. 

VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc (USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR J/IO_MODE 

358 ERROr’vIcTrOW 

359 ERROR_VIO_COL 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DET ACHED 

Remarks 

If a string write gets to the end of the line and is not complete, the string write continues at the beginning 
of the next line. If the write gets to the end of the screen, the write terminates. 

PM Considerations 

Write a character string with a repeated attribute string to the Advanced VIO presentation space. The 
caller must specify the starting location on the presentation space where the string is to be written. 


C Language 

#define INCLVIO 

USHORT rc « VioWrtCharStrAtt (CharStr, Length, Row, Column, Attr, VioHandle); 


PCH 

CharStr; 

/* String to be written */ 

USHORT 

Length; 

/* Length of string */ 

USHORT 

Row; 

/* Starting row position for output */ 

USHORT 

Col umn ; 

/* Starting column position for output */ 

PBYTE 

Attr; 

/* Attribute to be replicated */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 
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FAPI 


VioWrtCharStrAtt - 
Write Char String with Attr 


Assembler Language 


EXTRN VioWrtCharStrAtt: FAR 
INCL.VIO EQU 1 


PUSH? 

OTHER 

CharStr 

PUSH 

WORD 

Length 

PUSH 

WORD 

Row 

PUSH 

WORD 

Col umn 

PUSH? 

OTHER 

Attr 

PUSH 

WORD 

VioHandle 

CALL 

VioWrtCharStrAtt 


; String to be written 
; Length of string 
; Starting row position for output 
;Starting column position for output 
; Attribute to be replicated 
; Video handle 


Returns WORD 
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VioWrtNAttr - 
Write N Attributes 


FAPI 


This call writes an attribute to the display a specified number of times. 


VioWrtNAttr (Attr, Times, Row, Column, VIoHandte) 


Parameters 

Attr (PBYTE) - input 

Address of the attribute(s) (1 or 3 bytes) to be written. 

Times (USHORT) - input 

Number of times to write the attribute. 

Row ( USHORT) - input 
Starting cursor row. 

Column (USHORT) - input 
Starting cursor column. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436 ERROR_VIOJNVALID_HANDLE 

465 ERROR_VIO_DET ACHED 

Remarks 

If a repeated write gets to the end of the line and is not complete, the write continues at the beginning of 
the next line. If the write gets to the end of the screen, the write terminates. 

PM Considerations 

Write an attribute code to the Advanced VIO presentation space a specified number of times. The caller 
must specify the starting location on the presentation space where the string is to be written. 


C Language 

#define INCL_VI0 

USHORT rc = VioWrtNAttr (Attr, Times, Row, Column, VioHandle); 


PBYTE 

Attr; 

/* Attribute to be written */ 

USHORT 

Times; 

/* Repeat count */ 

USHORT 

Row; 

/* Starting row position for output */ 

USHORT 

Column; 

/* Starting column position for output */ 

HVIO 

VioHandle; 

/' k Video handle */ 

USHORT 

rc; 

/* return code */ 
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FAPI 


VioWrtNAttr - 
Write N Attributes 


Assembler Language 

EXTRN VioWrtNAttr: FAR 
INCLJIO EQU 1 


PUSH® OTHER Attr 

PUSH WORD Times 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioWrtNAttr 


; Attribute to be written 
; Repeat count 

; Starting row position for output 
; Starting column position for output 
; Video handle 


Returns WORD 
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VioWrtNCell - 
Write N Char/Attrs 


FAPI 


This call writes a cell (character-attribute pair) to the display a specified number of times. 


VioWrtNCell (Cell, Times, Row, Column, VIoHandle) 


Parameters 

Cell (PBYTE) - input 

Address of the character-attribute(s) cell (2 or 4 bytes) to be written. 

Times (USHORT) - input 

Number of times to write the cell. 

Row ( USHORT) - input 
Starting cursor row. 

Column ( USHORT) - input 
Starting cursor column. 

VIoHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 

Remarks 

If a repeated write gets to the end of the line and is not complete, the write continues at the beginning of 
the next line. If the write gets to the end of the screen, the write terminates. 

PM Considerations 

Write a cell (character-attribute) to the Advanced VIO presentation space a specified number of times. 
The caller must specify the starting location on the presentation space where the string is to be written. 


C Language 

Idefine INCL_VI0 

USHORT rc = VioWrtNCell (Cell , Times, Row. Column, VioHandle); 


PBYTE 

Cell; 

/* Cell to be written */ 

USHORT 

Times; 

/* Repeat count */ 

USHORT 

Row; 

/* Starting row position for output */ 

USHORT 

Column; 

/* Starting column position for output */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 
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FAPI 


VioWrtNCell - 
Write N Char/Attrs 


Assembler Language 

EXTRN VioWrtNCell: FAR 
I NCL_VI0 EQU 1 


PUSH@ OTHER Cell 

PUSH WORD Times 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioWrtNCell 


; Cel 1 to be written 
; Repeat count 

; Starting row position for output 
; Starting column position for output 
; Video handle 


Returns WORD 
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VioWrtNChar - 
Write N Characters 


FAPI 


VioWrtNChar writes a character to the display a specified number of times. 


VioWrtNChar (Char, Times, Row, Column, VioHandle) 


Parameters 

Char (PCH) — input 

Address of the character to be written. 

Times (USHORT) - input 

Number of times to write the character. 

Row ( USHORT) - input 
Starting cursor row. 

Column ( USHORT) - input 
Starting cursor column. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NO_ERROR 

355 ERROR_VIO_MODE 

358 ERRORVIOROW 

359 ERROR_VIO_COL 

436 ERROR_VIOJNVALIDJHANDLE 

465 ERRORVIODETACHED 

Remarks 

If a repeated write gets to the end of the line and is not complete, the write continues at the beginning of 
the next line. If the write gets to the end of the screen, the write terminates. 

PM Considerations 

Write a character to the Advanced VIO presentation space a number of times. The caller must specify the 
starting location on the presentation space where the string is to be written. 


C Language 

#define INCL_VI0 

USHORT rc - VioWrtNChar (Char, Tiroes, Row, Column, VioHandle); 


PCH 

Char; 

/* Character to be written */ 

USHORT 

Times; 

/* Repeat count */ 

USHORT 

Row; 

/* Starting row position for output */ 

USHORT 

Col utnn; 

f-k Starting column position for output */ 

HVIO 

VioHandle; 

/* Video handle */ 

USHORT 

rc; 

/* return code */ 
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FAPI 


VioWrtNChar - 
Write N Characters 


Assembler Language 

EXTRN VioWrtNChar: FAR 
INCL_VI0 EQU 1 


PU$H$ OTHER Char 

PUSH WORD Times 

PUSH WORD Row 

PUSH WORD Column 

PUSH WORD VioHandle 

CALL VioWrtNChar 


; Character to be written 
; Repeat count 

; Starting row position for output 
;Starting column position for output 
; Video handle 


Returns WORD 
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VioWrtTTY - 
Write TTY String 


FAPI 


This call writes a character string to the display starting at the current cursor position. At the completion 
of the write, the cursor is positioned at the first position beyond the end of the string. 


VioWrtTTY (CharStr, Length, VioHandle) 


Parameters 

CharStr ( PCH ) - input 

Address of the string to be written. 

Length (USHORT) - input 

Length of the character string in bytes. 

VioHandle (HVIO) - input 

This must be zero unless the caller is a Presentation Manager application, in which case it must be 
the value returned by VioGetPs. 

rc ( USHORT) - return 

Return code descriptions are: 

0 NOJERROR 

355 ERROR_VIO_MODE 

436 ERROR_VIO_INVALID_HANDLE 

465 ERROR_VIO_DETACHED 


Remarks 

If a string write gets to the end of the line and is not complete, the string write continues at the beginning 
of the next line. If the write gets to the end of the screen, the screen is scrolled, and the write continues 
until completed. 

The characters carriage return, line feed, backspace, tab, and bell are treated as commands rather than 
printable characters. Backspace is a non-destructive backspace. Tabs are expanded to provide 
standard 8-byte-wide fields. VioWrtTTY is the only video call affected by Ctrl-PrtSc and ANSI. 

Characters are written using the current attribute defined by ANSI or the default value 7. 

VioWrtTTY is supported in graphics mode to process ANSI sequences. This allows the application to 
enter and exit a graphics mode. 


PM Considerations 

Write a character string from the current cursor position in TTY mode to the Advanced VIO presentation 
space. The cursor is positioned after the last character written at the end of the write. 


C Language 

Idefine INCL.VI0 


USHORT rc - VioWrtTTY(CharStr, 

PCH CharStr; 

USHORT Length; 

HVIO VioHandle; 

USHORT rc; 


Length, VioHandle); 

/* String to be written */ 
/* Length of string */ 

/* Video handle */ 

/* return code */ 
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FAPI 


VioWrtTTY - 
Write TTY String 


Assembler Language 

EXTRN VioWrtTTY: FAR 
INCL_VI0 EQU 1 

PUSH? OTHER CharStr ; String to be written 

PUSH WORD Length ; Length of string 

PUSH WORD VioHandle ; Video handle 

CALL VioWrtTTY 

Returns WORD 
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Appendix A. Errors Returned from Base OS/2 Calls 


Numeric Order 

Error Number and Name 

0 NO_ERROR 

1 ERROR_INVALID_FUNCTION 

2 ERROR_FILE_NOT_FOUND 

3 ERROR_PATH_NOT_FOUND 

4 ERROR JTOO_MANY_OPEN_FILES 

5 ERROR_ACCESS_DENIED 

6 ERROR_INVALID_HANDLE 

7 ERROR_ARENA_TRASHED 

8 ERROR_NOT_ENOUGH_MEMORY 

9 ERROR _INVALID_BLOCK 

10 ERROR_BAD_ENVIRONMENT 

1 1 ERROR_BAD_FORMAT 

12 ERROR_INVALID_ACCESS 

13 ERROR_INVALID_DATA 

14 

15 ERROR_INVALID_DRIVE 

16 ERROR_CURRENT_DIRECTORY 

17 ERROR_NOT_SAMi_DEVICE 

18 ERROR_NO_MORE_FILES 

19 error_wr7te_protect 

20 ERROR_BAD_UNIT 

21 ERROR_NOT_READY 

22 ERROR_BAD_COMMAND 

23 ERROR_CRC 

24 ERROR_BAD_LENGTH 

25 ERROR_SEEK 

26 ERROR_NOT_DOS_DISK 

27 ERROR.SECTORJMOT^FOUND 

28 ERROR_OUT_OF_PAPER 

29 ERROR_WRITE_FAULT 

30 ERROR_READ_FAULT 

31 ERRORJBENJAILURE 

32 ERROR_SHARING_VIOLATION 

33 E R R 0 R_LOC K_V 1 0 L ATION 

34 ERROR_WRONG_DISK 

35 ERROR_FCB_UNAVAILABLE 

36 ERROR_SHARING_BUFFER_EXCEEDED 
37-49 

50 ERROR_NOT_SUPPORTED 
65 

73-79 

80 ERROR_FILE_EXISTS 

81 ERROR_DUP_FCB 

82 ERROR_CANNOT_MAKE 

83 ERROR_FAIL_l24 

84 E R R O R_OUT_OF_STR U CTU R ES 

85 error!already_assigned 

86 ERROR JNVALID_PASSWORD 

87 ERROR_INVALID_PARAMETER 

88 ERROR JMET_WRITE_FAULT 

89 ERROR_NO_PROC_SLOTS 

90 ERROR_NOT_FROZEN 

91 ERR_TSTOVFL 

92 ERR_TSTDUP 

93 ERROR_NOJTEMS 
95 ERRORJNTERRUPT 


Description 

No error occurred. 

Invalid function number. 

File not found. 

Path not found. 

Too many open files (no handles left). 
Access denied. 

Invalid handle. 

Memory control blocks destroyed. 
Insufficient memory. 

Invalid memory-block address. 

Invalid environment. 

Invalid format. 

Invalid access code. 

Invalid data. 

Reserved. 

Invalid drive specified. 

Attempting to remove current directory. 

Not same device. 

No more files. 

Attempt to write on write-protected diskette. 
Unknown unit. 

Drive not ready. 

Unknown command. 

Data error (CRC). 

Bad request structure length. 

Seek error. 

Unknown media type. 

Sector not found. 

Printer out of paper. 

Write fault. 

Read fault. 

General failure. 

Sharing violation. 

Lock violation. 

Invalid disk change. 

FCB unavailable. 

Sharing buffer overflow. 

Reserved. 

Network request not supported. 

Access denied. 

Reserved. 

File exists. 

Reserved. 

Cannot make directory entry. 

Fail on INT 24. 

Too many redirections. 

Duplicate redirection. 

Invalid password. 

Invalid parameter. 

Network device fault. 

No process slots available. 

System error. 

Timer service table overflow. 

Timer service table duplicate. 

No items to work on. 

Interrupted system call. 
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99 ERROR_DEVICE_IN_USE 

100 ERROR" TOO_MANY_SEMAPHORES 

101 ERROR_EXCL_SEM_ALREADY_OWNED 

102 ERROR_SEMJS_SET 

103 ERROR_TOO_MANY_SEM_REQUESTS 

104 ERROR JNVALID_AT_INTERRUPT_TIME 

105 ERROR_SEM_OWNER_DIED 

106 ERROR_SEM_USER_LIMIT 

107 ERROR_DISK_CHANGE 

108 ERROR_DRIVE_LOCKED 

109 ERROR_BROKEN_PIPE 

110 ERROR_OPEN_F AILED 

111 ERRORJ3UFFER_OVERFLOW 

112 ERROR_DISK_FULL 

113 ERROR_NO_MORE_SEARCH_HANDLES 

114 ERRORJNVALID_TARGET_HANDLE 

115 ERROR_PROTECTION_VIOLATION 

116 ERROR^VIOKBD_REQUEST 

117 ERROR JNVALID_CATEGORY 

118 ERROR_INVALID_VERIFY_SWITCH 

119 ERROR_BAD_DR?VER_LEVEL 

120 ERROR_CALL_NOT_IMPLEMENTED 

121 error_sem_timeout 

122 ERROR_INSUFFICIENT_BUFFER 

123 ERROR JNVALID_N AM E 

124 ERRORINVALIDLEVEL 

125 ERROR_NO_VOLUME_LABEL 

126 ERROR_MOD_NOT_FOUND 

127 ERROR_PROC_NOT_FOUND 

128 ERROR_WAIT_NO_CHILDREN 

129 ERROR_CHILD_NOT_COMPLETE 

130 ERRORJDIRECT_ACCESS_HANDLE 

131 ERROR_NEGATIVE_SEEK 

132 ERROR.SEEK_ON_DEVICE 

133 ERROR IS JOIN TARGET 

134 ERROR_IS_JOINED 

135 ERRORJS_SUBSTED 

136 errorInot_joined 

137 ERROR_NOT_SUBSTED 

138 ERROR_JOIN_TOJOIN 

139 E R RO R_SU BST_TO_SUBST 

140 ERROR_JOIN_TO_SUBST 

141 ERROR_SUBST_TO_JOIN 

142 ERROR_BUSY_DRIVE 

143 ERROR_SAME~DRIVE 

144 ERROR_DIR_NOT_ROOT 

145 ERROR_DIR_NOT_EMPTY 

146 ERROR JS_SUBST_PATH 

147 ERROR JS_JOIN_PATH 

148 ERROR_PATH_BUSY 

149 ERROR_IS_SUBST_TARGET 

150 ERROR_SYSTEM_TRACE 

151 ERROR_INVALID_EVENT_COUNT 

152 ERROR_TOO_MANY_MUXWAITERS 

153 errorjnva"lid_list_format 

154 ERRORJ.ABEL_TOO_LONG 

155 ERROR JTOO_MANY_TCBS 

156 ERROR_SIGNAL_REFUSED 

157 ERROR_DISCARDED 

158 ERROR JMOT_LOCKED 


Device in use. 

User/system open semaphore limit exceeded. 

Exclusive semaphore already owned. 

DosCloseSem found semaphore set. 

Too many exclusive semaphore requests. 

Operation invalid at interrupt time. 

Previous semaphore owner terminated without freeing 
semaphore. 

Semaphore limit exceeded. 

Insert drive B disk into drive A. 

Drive locked by another process. 

Write on pipe with no reader. 

Open/create failed due to explicit fail command. 

Buffer passed to system call too small to hold return data. 
Not enough space on the disk. 

Cannot allocate another search structure and handle. 
Target handle in DosDupHandle invalid. 

Bad user virtual address. 

Error on display write or keyboard read. 

Category for DevlOCtl not defined. 

Invalid value passed for verify flag. 

Level four driver not found. 

Invalid function called. 

Time out occurred from semaphore API function. 

Data buffer too small. 

Illegal character or bad file-system name. 
Non-implemented level for information retrieval or setting. 
No volume label found with DosQFsInfo command. 

Module handle not found with getprocaddr, getmodhandle. 
Procedure address not found with getprocaddr. 

DosCwait finds no children. 

DosCwait children not terminated. 

Handle operation invalid for direct disk-access handles. 
Attempting seek to negative offset. 

Application trying to seek on device or pipe. 

Drive has previously joined drives. 

Drive is already joined. 

Drive is already substituted. 

Cannot delete drive that is not joined. 

Cannot delete drive that is not substituted. 

Cannot join to a joined drive. 

Cannot substitute to a substituted drive. 

Cannot join to a substituted drive. 

Cannot substitute to a joined drive. 

Specified drive is busy. 

Cannot join or substitute a drive to a directory on the 
same drive. 

Directory must be a subdirectory of the root. 

Directory must be empty to use join command. 

Path specified is being used in a substitute. 

Path specified is being used in join. 

Path specified is being used by another process. 

Cannot join or substitute drive having directory that is 
target of a previous substitute. 

System trace error. 

DosMuxSemWait errors. 

System limit of 100 entries reached. 

Invalid list format. 

Volume label too big. 

Cannot create another TCB. 

Signal refused. 

Segment is discarded. 

Segment not locked. 
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159 ERROR_BAD_THREADID_ADDR 

160 ERROR_BAD_ARGUMENTS 

161 ERROR_BAD_PATHNAME 

162 ERROR_SIGN APPENDING 

163 ERROR_UNCERTAIN_MEDIA 

164 error_max_thrds~reached 

165 ERROR_MONITORS_NOT_SUPPORTED 

166 ERROR,UNC_DRIVER_NOT_INSTALLED 

167 ERROR_LOCK_FAILED 

168 error_swapTo_failed 

169 ERROR_SWAPIN_FAILED 

170 ERROR_BUSY 

180 ERROR _INVALID_SEGMENT_NUMBER 

181 ERROR JNVALID_CALLG ATE 

182 ERROR_INVALID_ORDlNAL 

183 ERROR_ALREADY_EXISTS 

184 ERROR_NO_CHILD_PROCESS 

185 ERROR_CHILD_ALIVE_NOWAIT 

186 ERRORJNVALID_FLAG_N UMBER 

187 ERROR_SEMJS|OT_FOUND 

188 ERROR_INVALID_STARTING_CODESEG 

189 ERROR_INVALID_STACKSEG 

190 ERRORJNVALID.MODULETYPE 


191 ERROR_INVALID_EXE_SIGNATURE 

192 ERROR_EXE_MARKED_INVALID 


Bad thread-identity address. 

Bad environment pointer. 

Bad path name passed to exec. 

Signal already pending. 

ERRORJ24 mapping. 

No more process slots. 

ERRORJ24 mapping. 

Default redir return code 
Locking failed. 

Swap 10 failed. 

Swap in failed. 

Busy. 

Invalid segment number. 

Invalid call gate. 

Invalid ordinal. 

Shared segment already exists. 

No child process to wait for. 

NoWait specified and child alive. 

Invalid flag number. 

Semaphore does not exist. 

Invalid starting code segment, incorrect END (label) direc- 
tive. 

Invalid stack segment. 

Invalid module type - dynamic-link library file cannot be 
used as an application. Application cannot be used as a 
dynamic-link library. 

Invalid EXE signature - file is DOS mode program or 
improper program. 

EXE marked invalid - link detected errors when applica- 
tion created. 


193 ERROR_BAD_EXEJ = ORMAT 


Bad EXE format - file is DOS mode program or improper 


program. 

194 ERROR JTERATED_DATAJEXCEEDS_64K Iterated data exceeds 64KB - more than 64KB of data in 

one of the segments of the file. 

195 ERRORJNVALIDMINALLOCSIZE Invalid minimum allocation size - size is specified to be 

less than the size of the segment data in the file. 

196 ERROR_DYNLINK_FROMJNVALlD_RING Dynamic link from invalid privilege level - privilege level 

2 routine cannot link to dynamic-link libraries. 


197 ERRORJOPL_NOT_ENABLED IOPL not enabled - IOPL set to “NO" in CONFIG.SYS. 

198 ERROR_INVALID_SEGDPL Invalid segment descriptor privilege level - can only 


1 99 ERROR_AUTODATASEG_EXCEEDS_64k 

200 ERROR_RI NG2SEG_M UST_BE_MOVABLE 

201 ERROR_RELOC_CHAIN_XEEDS_SEGLIM 

202 ERROR JNFLOOPJN_RELOC_CH AIN 

203 ERROR_ENVVAR_NOT_FOUND 

204 ERROR_NOT_CURRENT_CTRY 

205 ERROR_NO_SIGNAL_SENT 


have privilege levels of 2 and 3. 

Automatic data segment exceeds 64KB. 

Privilege level 2 segment must be movable. 

Relocation chain exceeds segment limit. 

Infinite loop in relocation chain segment. 

Environment variable not found. 

Not current country. 

No signal sent - no process in the command subtree has 


206 ERROR_FILENAME_EXCED_RANGE 

207 ERROR_RING2_STACKJN_USE 

208 ERROR_META_EXPANSION_TOO_LONG 

209 ERROR_INVALID_SIGNAL_NUMBER 

210 ERROR_THREAD_1_IN ACTIVE 

211 ERROR_INFO_NOT_AVAIL 

212 ERRORJ-OCKED 

213 ERROR_BAD_DYNALINK 

214 ERROR_TOO_MANY_MODULES 

215 ERROR_NESTING_NOT_ALLOWED 

217 ERROR_ZOMBIE_PROCESS 

218 ERROR_STACKJN_HIGH_MEMORY 

219 ERRORJNVALID_EXITROUTINE_RING 

220 ERROR_GETBUF_FAILED 


a signal handler. 

File name or extension greater than “8.3” characters. 
Privilege level 2 stack in use. 

Meta (global) expansion is too long. 

Invalid signal number. 

Inactive thread. 

File system information not available for this file. 
Locked error. 

Attempted to execute non-family API in DOS mode. 
Too many modules. 

Nesting not allowed. 

Zombie process. 

Stack in high memory. 

Invalid exit routine ring. 

Get buffer failed. 
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221 ERROR_FLUSHBUF_FAILED 

222 ERROR_TRANSFER_TOOJ-ONG 

228 ERR0R_N0_CH1LDREN 

229 ERROR_INVALID_SCREEN_GROUP 

230 ERROR_BAD_PIPE 

231 ERROR_PIPE_BUSY 

232 ERROR_NO_DATA 

233 ERROR_PIPE_NOT_CONNECTED 

234 ERROR_MORE_DATA 

240 ERROR_VC_DISCONNECTED 

250 ERROR_CIRCULARITY_REQUESTED 

251 ERROR_DIRECTORYJN_CDS 

252 ERROR_INVALID_FSD_NAME 

253 ERRORJNVALID_PATH 

254 ERROR_INVALID_EA_NAME 

255 ERROR_EA_LIST_INCONSISTENT 

256 ERROR_EAJJSTTOO_LONG 

257 ERROR JNJO_META_MATCH 

259 ERROR_NO_MOREJTEMS 

260 ERROR_SEARCH_STRUC_REUSED 

261 ERROR_CHAR_NOT_FOUND 

262 ERROR_TOO_MUCH_STACK 

263 ERRORJNVALID_ATTR 

264 ERRORJNVALID_STARTING_RING 

265 ERRORINVALIDDLLJNITRING 

266 E R R O R_C AN NOT_CO PY 

267 ERROR_DIRECTORY 

268 ERROR_OPLOCKED_FILE 

269 ERROR_OPLOCK_THREAD_EXISTS 

270 ERROR_VOLUME_CHANGED 
271-273 

274 ERROR_ALREADY_SHUTDOWN 

275 ERR0R_EAS_D1DNT_FIT 

303 ERROR_INVALID_PROCID 

304 ERROR_INVAL!D_PDELTA 

305 ERROR_NOT_DESCENDANT 

306 ERROR_NOT_SESSION_MANAGER 

307 ERROR_INVALID_PCLASS 

308 ERROR JNVALID_SCOPE 

309 ERRORJNVALID_THREADID 

310 ERROR_DOSSUB_SHRINK 

311 ERRORJDOSSUBJslOMEM 

312 ERROR_DOSSUB~OVERLAP 

313 ERROR_DOSSUB_BADSIZE 

314 ERROR_DOSSUB_BADFLAG 

315 ERROR_DOSSUB_BADSELECTOR 

316 ERROR_MR_MSG_TOO_LONG 

317 ERROR_MR_MID_NOT_FOUND 

318 ERROR_MRJJN_ACC_MSGF 

319 ERROR_MR_INV_MSGF_FORMAT 

320 E RROR_M R_l N VJVCOUNT 

321 ERROR_MRJJN_PERFORM 

322 ERRORJTSJVAKEUP 

323 ERROR_TS_SEM HANDLE 

324 ERROR_TS_NOTIMER 

326 ERROR_TS_HANDLE 

327 ERROR_TS_DATETIME 

328 ERROR_SYS_INTERNAL 

329 ERROR_QUE_CURRENT_NAME 

330 E R RO R_QU E_P ROC_N OT_0 W NED 

331 ERROR_QUE_PROC_OWNED 


Flush buffer failed. 

Transfer is too long. 

No child process. 

Invalid session. 

Non-existent pipe or bad operation. 

Pipe is busy. 

No data available on non-blocking read. 

Pipe was disconnected by server. 

More data is available. 

Session was dropped due to errors. 

Renaming a directory that would cause a circularity 
problem. 

Renaming a directory that is in use. 

Trying to access nonexistent FSD. 

Bad pseudo device. 

Bad character in name, or bad cbName. 

List does not match its size, or bad EAs in list. 
FEAList > 64K-1 bytes. 

String doesn't match expression. 

DosQFSAttach ordinal query. 

DOS mode findfirst/next search structure reused. 
Character not found. 

Stack request exceeds system limit. 

Invalid attribute. 

Invalid starting ring. 

Invalid DLL INIT ring. 

Cannot copy. 

Used by DOSCOPY in doscalll. 

Oplocked file. 

Oplock thread exists. 

Volume changed. 

Reserved. 

System already shutdown. 

EAS didnt fit. 

Invalid process identity. 

Invalid priority delta. 

Not descendant. 

Requestor not session manager. 

Invalid P class. 

Invalid scope. 

Invalid thread identity. 

Cannot shrink segment — DosSubSet. 

No memory to satisfy request - DosSubAlloc. 
Overlap of specified block with an allocated memory 
DosSubFree. 

Bad size parameter - DosSubAlloc or DosSubFree. 
Bad flag parameter - DosSubSet. 

Invalid segment selector. 

Message too long for buffer. 

Message identity number not found. 

Unable to access message file. 

Invalid message file format. 

Invalid insertion variable count. 

Unable to perform function. 

Unable to wake up. 

Invalid system semaphore. 

No timers available. 

Invalid timer handle. 

Date or time invalid. 

Internal system error. 

Current queue name does not exist. 

Current process does not own queue. 

Current process owns queue. 
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332 ERROR_QUEJDUPLICATE 

333 ER ROR_QUE_ELEM ENT_NOT_EXIST 

334 ERROR_QUE_NO_M EMORY “ 

335 ERROR_QUEJNVALID_NAME 

336 ERROR_QUEJNVALID_PRIORITY 

337 ERROR_QUEJNVALID_HANDLE 

338 ERROR_QUE_LINK_NOT_FOUND 

339 ERROR_QUE_MEMORY_ERROR 

340 ERROR_QUE_PREV_AT_END 

341 error_que_proc_no_access 

342 ERROR_QUE_EMPTY 

343 ERROR_QUE_NAME_NOT_EXIST 

344 ERROR_QUE_NOTJNITIALIZED 

345 ERROR_QUE_UNABLE_TO_ACCESS 

346 ERROR_QUE_UNABLeItoIaDD 

347 ERROR^QUE_UNABLE_TOJNIT 

349 ERROR_VIO_INVAUD_MASK 

350 ERROR_VIO_PTR 

351 ERR0R_VI0lAPTR 

352 ERROR_VIO_RPTR 

353 ERROR_VIO_CPTR 

354 ERROR_VIO_LPTR 

355 ERROR_VIO_MODE 

356 ERROR_VIO_WIDTH 

357 E R ROR_V 1 0_ATTR 

358 ERROR_VIO_ROW 

359 ERROR_VIO_COL 

360 ERROR_VIO_TOPROW 

361 ERROR_VIO_BOTROW 

362 ERROR_VIO_RIGHTCOL 

363 ERROR_VIO_LEFTCOL 

364 ERROR_SCS_CALL 

365 ERROR_SCS_VALUE 

366 ERROR_VIO_WAIT_FLAG 

367 ERRORJ/IOJJNLOCK 

368 ERROR_SGS_NOTSESSlON_MGR 

369 ERROR_SMGJNVALID_SGID 

369 ERROR_SMGJNVALID_SESSIONJD 

370 ERROR_SMG_NOSG 

370 ERROR_SMG_NO_SESSIONS 

371 ERROR_SMG_GRP_NOT_FOUND 

371 ERROR_SMG_SESSION_NOT_FOUND 

372 ERROR_SMG_SET_TITLE 

373 ERROR_KBD_PARAMETER 

374 ERROR_KBD_NO_DEVICE 

375 ERROR_KBD_INVALIDJOWAIT 

376 ERROR_KBD_INVALID_LENGTH 

377 ERROR J<BDJNVALID_ECHO_M ASK 

378 ERROR_KBD_INVALIDJNPUT~MASK 

379 ERROR_MONJNVALID~PARMS 

380 error_mon_invalidIdevname 

381 ERROR_MON_INVALID_HANDLE 

382 ERR0R_M0N_BUFFERJ-00_SMALL 

383 ERROR_MON_BUFFER_EMPTY 

384 ERROR_MON_DATA_TOO_LARGE 

385 ERROR_MOUSE_NO_DEVICE 

386 ERROR_MOUSE_INV_HANDLE 

387 ERROR_MOUSEJNV_PARMS 

388 ERROR_MOUSE_CANT_RESET 

389 ERROR_MOUSE_DISPLAY_PARMS 

390 ERROR_MOUSE_INV_MODULE 

391 ERROR_MOUSE_INV_ENTRY_PT 

392 ERROR_MOUSEJNV_MASK 


Duplicate queue name. 

Queue element does not exist. 

Inadequate queue memory. 

Invalid queue name. 

Invalid queue priority parameter. 

Invalid queue handle. 

Queue link not found. 

Queue memory error. 

Previous queue element was at end of queue. 
Process does not have access to queues. 
Queue is empty. 

Queue name does not exist. 

Queues not initialized. 

Unable to access queues. 

Unable to add new queue. 

Unable to initialize queues. 

Invalid function replaced. 

Invalid pointer to parameter. 

Invalid pointer to attribute. 

Invalid pointer to row. 

Invalid pointer to column. 

Invalid pointer to length. 

Unsupported screen mode. 

Invalid cursor width value. 

Invalid cursor attribute value. 

Invalid row value. 

Invalid column value. 

Invalid TopRow value. 

Invalid BotRow value. 

Invalid right column value. 

Invalid left column value. 

Call issued by other than sm 
Value is not for save or restore. 

Invalid wait flag setting. 

Screen not previously locked. 

Caller not session manager. 

Invalid session identity. 

Invalid session ID. 

No sessions available. 

No sessions available. 

Session not found. 

Session not found. 

Title sent by shell or parent cannot be changed. 
Invalid parameter to keyboard. 

No device. 

Invalid I/O wait specified. 

Invalid length for keyboard. 

Invalid echo mode mask, 
invalid input mode mask, 
invalid parameters to DosMon. 

Invalid device name string. 

Invalid device handle. 

Buffer too small. 

Buffer is empty. 

Data record too large. 

Mouse device closed (invalid device handle). 
Mouse device closed (invalid device handle). 
Parameters invalid for display mode. 

Function assigned and cannot be reset. 
Parameters invalid for display mode. 

Module not valid. 

Entry point not valid. 

Function mask invalid. 
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393 NO_ERROR_MOUSE_NO_DATA No valid data. 

394 NO_ERROR_MOUSE_PTR_DRAWN Pointer drawn. 

395 ERROR JNVALI ^FREQUENCY Invalid frequency for beep. 

396 ERROR_NLS_NO_COUNTRY_FILE Cannot find COUNTRY.SYS file. 

397 ERROR_NLS_OPEN_FAILED Cannot open COUNTRY.SYS file. 

398 ERROR_NLS_NO_CTRY_CODE Country code not found. 

398 ERROR_NO_COUNTRY_OR_CODEPAGE Country code not found. 

399 ERROR_NLS_TABLE_TRUNCATED Table returned information truncated, buffer too small. 

400 ERROR_NLS_BAD_TYPE Selected type does not exist. 

401 ERROR_NLslTYPE_NOT_FOUND Selected type not in file. 

402 ERROR_VIO_SMG_ONLY Valid from session manager only. 

403 ERROR_VIO_INVALID_ASCIIZ Invalid ASCIIZ length. 

404 ERROR_VIO_DEREGISTER VioDeRegister not allowed. 

405 ERROR_VIO_NO_POPUP Pop-up window not allocated. 

406 ERROR_VIO_EXISTING_POPUP Pop-up window on screen (NoWait). 

407 ERROR_KBD_SMG_ONLY Valid from session manager only. 

408 ERROR_KBDJNVALlD_ASCIIZ Invalid ASCIIZ length. 

409 ERROR_KBD_INVALID_MASK Invalid replacement mask. 

410 ERROR_KBD_REGISTER KbdRegister not allowed. 

411 ERROR_KBDJDEREGISTER KbdDeRegister not allowed. 

412 ERROR~MOUSE_SMG_ONLY Valid from session manager only. 

413 ERROR_MOUSE_INVALID_ASCIIZ Invalid ASCIIZ length. 

414 ERROR_MOUSEJNVALID_MASK Invalid replacement mask. 

415 ERROR_MOUSE_REGISTER Mouse register not allowed. 

416 ERROR_MOUSE_DEREGISTER Mouse deregister not allowed. 

417 ERROR_SMG_BAD_ACTION Invalid action specified. 

418 ERROR_SMGJNVALID_CALL INIT called more than once or invalid session identity. 

419 ERROr”sCS_SG_NOTFOUND New session number. 

420 ERROR_SCS_NOT_SHELL Caller is not shell. 

421 ERROR_VIO_INVALID_PARMS Invalid parameters passed. 

422 ERROR[violFUNCTION_OWNED Save/restore already owned. 

423 ERROR_VIO_RETURN Non-destruct return (undo). 

424 ERROR_SCSJNVALID_FUNCTION Caller invalid function. 

425 ERROR_SCS_NOT_SESSION_MGR Caller not session manager. 

426 ERROR_VIO_REGISTER Vio register not allowed. 

427 ERROR_VIO_NO_MODE_THREAD No mode restore thread in SG. 

428 ERROR_VIO_NO_SAVE_RESTORE_THD No save/rest thread in SG. 

429 ERROR_VIO_IN_BG Function invalid in background. 

430 ERROR_VIOJLLEGAL_DURING_POPUP Function not allowed during pop-up window. 

431 ERROR_SMG_NOT_BASESHELL Caller is not the base shell. 

432 ERROR_SMGJ3AD_STATUSREQ Invalid status requested. 

433 ERROr‘qUEJNVALID_WAIT NoWait parameter out of bounds. 

434 ERROR_VIO_LOCK Error returned from Scroll Lock. 

435 ERROR_MOUSEJNVALID_IOWAIT Invalid parameters for lOWait. 

436 ERROR_VIO_INVALID_HANDLE Invalid VIO handle. 

437 ERROR_VIOJLLEGAL_DURING_LOCK Function not allowed during screen lock. 

438 ERRORiviOJNVALIDlENGTH Invalid VIO length. 

439 ERROR J<BDJNVALIDJHANDLE Invalid KBD handle. 

440 ERROR_KBD_NO_MORE_HANDLE Ran out of handles. 

441 ERROR_KBD_CANNOTCREATE_KCB Unable to create kcb. 

442 ERROR_KBD_CODEPAGE_LOADJNCOMPL Unsuccessful code-page load. 

443 ERROR_KBDJNVALID_CODEPAGEJD Invalid code-page identity. 

444 ERRORJ<BD_NO_CODEPAGE_SUPPORT No code page support. 

445 ERROR_KBD_FOCUS_REQUIRED Keyboard focus required. 

446 ERROR_KBDJ : OCUS_ALREADY_ACTIVE Calling thread has an outstanding focus. 

447 ERROR~KBD~KEYBOARD_BUSY Keyboard busy. 

448 ERROR_KBD_INVALID_CODEPAGE Invalid code page. 

449 ERROR_KBD_UNABLE_TO_FOCUS Focus attempt failed. 

450 ERROR_SMG_SESSION_NON_SELECT Session is not selectable. 

451 ERROR_SMG_SESSION_NOT_FOREGRND Parent/child session not foreground. 

452 ERROR_SMG_SESSION_NOT_PARENT Not parent of requested child. 

453 ERROR_SMG_INVALID_START_MODE Invalid session start mode. 

454 ERROR_SMG_INVALID_RELATED_OPT Invalid session start related option. 
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455 ERROR_SMG_INVALID_BOND_OPTION 

456 ERROR_SMGJNVALID_SELECT_OPT 

457 ERROR_SMG_STARTJN_BACKGROUND 

458 ERROR_SMGJNVALID_STOP_OPTION 

459 ERROR_SMG_BAD_RESERVE 

460 ERROR_SMG_PROCESS_NOT_PARENT 

461 ERROR_SMGJNVALID_DATA_LENGTH 

462 ERROR_SMG_NOT_BOUND 

463 ERROR_SMG_RETRY_SUB_ALLOC 

464 ERROR_KBD_DETACHED 

465 ERROR_VIO_DETACHED 

466 ERROR_MOU_DETACHED 

467 ERROR_VIO_FONT 

468 ERROR_VIOJJSER_FONT 

469 ERROR_VIO_BAD_CP 

470 ERROR_VIO_NO_CP 

471 ERROR_VIO_NA_CP 

472 ERROR_INVALID_CODE_PAGE 

473 ERROR_CPL!ST_TOO_SMALL 

474 ERROR_CP_NOT_MOVED 

475 ERROR_MODE_SWITCHJNIT 

476 ERROR_CODE_PAGE_NOT_FOUND 

477 ERRORJJNEXPECTED_SLOT_RETURNED 

478 ERROR_SMG_INVAUD_TRACE_OPTION 

479 ERROR_VIOJNTERNAL_RESOURCE 

480 ERROR_VIO_SHELLJNIT 

481 ERROR_SMG.NO_HARD_ERRORS 

482 ERROR_CP_SWITCHJNCOMPLETE 

483 ERROR_VIO_TRANSPARENT_POPUP 

484 ERROR_CRITSEC_OVERFLOW 

485 ERROR_CRITSEC_UNDERFLOW 

486 ERROR_VIO_BAD_RESERVE 

487 ERROR JNVALID_ADDRESS 

488 ERROR~ZERO_SELECTORS_REQUESTED 

489 ERROR_NOT_ENOUGH_SELECTORS_AVA 

490 ERRORJNVALID_SELECTOR 

491 ERROR_SMGJNVALID_PROGRAM_TYPE 

492 ERROR_SMGJNVALID_PGM_CONTROL 

493 ERROR_SMG_INVALID INHERIT_OPT 

494 E R R 0 R_VIO_EXTEN DE D_SG 

495 E R R O R_VIO_N OT_PRES_M G R_SG 

496 ERROR_VIO_SHIELD_OWNED~ 

497 ERROR_VIO_NO_MORE_HANDLES 

498 ERROR_VIO_SEE_ERROR_LOG 

499 E RRO R_VI 0_ASSOCI ATED_DC 

500 ERROR_KBD_NO_CONSOLE 

501 ERROR_MOUSE_NO_CONSOLE 

502 ERROR JtfOUSEJNVALIDHANDLE 

503 ERROR_SMGJNVALID_DEBUG_PARMS 

504 ERROR_KBD_EXTENDED_SG 

505 ERROR_MOU_EXTENDED_SG 

506 ERROR_SMG_INVALID_ICON_FILE 

Alphabetic Order 

Error Name and Number 

ERROR_ACCESS_DENIED 5 

ERROR_ALREADY_ASSIGNED 85 

ERROR_ALREADY_EXISTS 183 

ERROR_ALREADY_SHUTDOWN 274 
ERROR_ARENA_TRASHED 7 

ERROR_AUTODATASEG_EXCEEDSJ)4k 199 
ERROR_BAD_ARGUMENTS 160 


Invalid session bond option. 

Invalid session select option. 

Session started in background. 

Invalid session stop option. 

Reserved parameters not zero. 

Session parent process already exists. 

Invalid data length. 

Parent not bound. 

Retry request block allocation. 

This call not allowed for detached PID. 

This call disallowed for detached pid. 

This call disallowed for detached pid. 

No font available to support mode. 

User font active. 

Invalid code page specified. 

System displays do not support code page. 
Current display does not support code page. 
Invalid code page. 

Code page list is too small. 

Code page not moved. 

Mode switch initialization error. 

Code page not found. 

Internal error. 

Invalid start session trace indicator. 

VIO internal resource error. 

VIO shell initialization error. 

No session manager hard errors. 

DosSetCp unable to set KBD or VIO code page. 
Error during VIO pop-up window. 

Critical section overflow. 

Critical section underflow. 

Reserved parameter is not zero. 

Bad physical address. 

At least one selector must be requested. 

Not enough GDT selectors to satisfy request. 
Not a GDT selector. 

Invalid program type. 

Invalid program control. 

Bad inherit option. 


Description 

Access denied. 

Duplicate redirection. 

Shared segment already exists. 

System already shutdown. 

Memory control blocks destroyed. 
Automatic data segment exceeds 64KB. 
Bad environment pointer. 
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ERROR_BAD_COMMAND 22 

ERROR_BAD_DRIVER_LEVEL 119 

ERROR_BAD_DYNALINK 213 

ERROR_BAD_ENVIRONMENT 10 

ERROR_BAD_EXE_FORMAT 193 

ERROR_BAD_FORMAT 1 1 

ERROR_BAD_LENGTH 24 

ERROR_BAD_PATHNAME 161 

ERROR_BAD_PIPE 230 

ERROR_BAD_THREADID_ADDR 159 
ERROR_BAD_UNIT 20 

ERROR_BROKEN_PIPE 109 

ERROR_BUFFER_OVERFLOW 1 1 1 

ERRORJBUSY 170 

ERROR_BUSY_DRIVE 142 

error^callInotjmplemented 120 

E R R O R_C ANNOT_COPY 266 

ERROR_CANNOT_MAKE 82 

ERROR_CHAR_NOTFOUND 261 

ERROR_CHILD_ALIVE_NOWAIT 185 

ERROR_CHILD_NOT_COMPLETE 129 
ERROR_CIRCULARITY_REQUESTED 250 

ERROR_CODE_PAGE_NOT_FOUND 476 
ERROR_CPLIST_TOO_SMALL 473 

E RRO R_C P_N OT_M O VE D 474 

ERROR_CP_SWITCHJNCOMPLETE 482 
ERROR_CRC 23 

ERROR_CRITSEC_OVERFLOW 484 
ERROR_CRITSEC_UNDERFLOW 485 
ERROR_CURRENT_DIRECTORY 1 6 

ERROR_DEVICE_IN_USE 99 

ERRORDIRECTORY 267 

ERRORJDI RECTORY JN_CDS 251 

ERROR_DIRECT_ACCESS_HANDLE 130 
ERROR_DIR_NOTJEMPTY 145 

E RROR_DI R_NOT_ROOT 144 

ERROR.DISCARDED 157 

ERROR_DISK_CHANGE 107 

ERROR_DISK_FULL 112 

ERROR_DOSSUB_BADFLAG 314 

ERRORJDOSSUBJ3ADSELECTOR 315 
ERROR_DOSSUB_BADSIZE 313 

ERROR_DOSSUB_NOMEM 31 1 

ERROR_DOSSUB_OVERLAP 312 

ERROR_DOSSUB_SHRINK 310 

ERROR_DRIVEJ_OCKED 108 

ERROR JDUPjbB 81 

ERROR_DYNLINK_FROMJNVALI DURING 196 

ERROR_EA_LISTJNCONSISTENT 255 
ERROR_EA_LIST_TOO_LONG 256 

ERROR_EAS_DIDNT_FIT 275 

ERROR_ENVVAR_NOT_FOUND 203 
ERROR_EXCL_SEM_ALREADY_OWNED 101 
ERROR_EXE_MARKED_INVALID 192 

ERR0R_FAIL_I24 83 

ERROR_FCBJJNAVAILABLE 35 

ERROR_FILENAME_EXCED_RANGE 206 
ERROR_FILE_EXISTS 80 


Unknown command. 

Level four driver not found. 

Attempted to execute non-family API in DOS mode. 

Invalid environment. 

Bad EXE format - file is DOS mode program or improper 
program. 

Invalid format. 

Bad request structure length. 

Bad path name passed to exec. 

Non-existent pipe or bad operation. 

Bad thread-identity address. 

Unknown unit. 

Write on pipe with no reader. 

Buffer passed to system call too small to hold return data. 
Busy. 

Specified drive is busy. 

Invalid function called. 

Cannot copy. 

Cannot make directory entry. 

Character not found. 

NoWait specified and child alive. 

DosCwait children not terminated. 

Renaming a directory that would cause a circularity 
problem. 

Code page not found. 

Code page list is too small. 

Code page not moved. 

DosSetCp unable to set KBD or VIO code page. 

Data error (CRC). 

Critical section overflow. 

Critical section underflow. 

Attempting to remove current directory. 

Device in use. 

Used by DOSCOPY in doscalll. 

Renaming a directory that is in use. 

Handle operation invalid for direct disk-access handles. 
Directory must be empty to use Join command. 

Directory must be a subdirectory of the root. 

Segment is discarded. 

Insert drive B disk into drive A. 

Not enough space on the disk. 

Bad flag parameter - DosSubSet. 

Invalid segment selector. 

Bad size parameter - DosSubAlloc or DosSubFree. 

No memory to satisfy request - DosSubAlloc. 

Overlap of specified block with an allocated memory - 
DosSubFree. 

Cannot shrink segment - DosSubSet. 

Drive locked by another process. 

Reserved. 

Dynamic link from invalid privilege level — privilege level 
2 routine cannot link to dynamic-link libraries. 

List does not match its size, or bad EAs in list. 

FEAList > 64K-1 bytes. 

EAS didnt fit. 

Environment variable not found. 

Exclusive semaphore already owned. 

EXE marked invalid - link detected errors when applica- 
tion created. 

Fail on INT 24. 

FCB unavailable. 

File name or extension greater than "8.3" characters. 

File exists. 
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ERROR_FILE_NOT_FOUND 2 

ERROR_FLUSHBUF_FAILED 221 
ERROR_GEN_FAILURE 31 

ERR0RJ3ETBUF_FAILED 220 

ERRORJNFLOOPJN_RELOC_CHAIN 202 
ERRORJNFO_NOT_AVAIL 211 

ERRORJNSUFFICIENT_BUFFER 122 
ERRORJNTERRUPT ~ 95 

E R ROR _l NVALI D_ACCESS 1 2 

ERRORJNVALID_ADDRESS 487 

ERROR_INVALID_ATTR 263 

ERROR JNVALIdIaT_!NTERRUPT_TIME 104 
ERRORJNVALID.BLOCK 9 

ERROR JNVALID_CALLGATE 181 

ERROR JNVALID_CATEGORY 117 

ERROR_INVALIDCODE_PAGE 472 

E R ROR J NVALI D_D ATA 1 3 

ERRORJNVALID_DLLJNIT_RING 265 
ERROR_INVALID_DRIVE ~ 15 

E R RORJ NVALI D_E A_N AM E 254 

ERROR_INVALID_EVENT_COUNT 151 
ERROR_INVALID_EXE_SIGNATURE 191 

ERRORJNVALID_EXITROUTINE_RING 219 
ERROR_INVALID_FLAG_NUMBER 186 
ERROR_INVALID_FREQUENCY 395 

ERRORJNVALIDFSDNAME 252 

ERROR JNVALIDFUNCTION 1 

ERROR JNVALIDJHANDLE 6 

ERRORJNVALIDLEVEL 124 

ERROR_INVALID_LIST__FORMAT 153 
ER ROR J NVALI D_M I NALLOCSIZE 195 

ERROR_INVALID_MODULETYPE 1 90 


ERROR_INVALID_NAME 123 

ERRORJNVALID_ORDINAL 182 

ERROR JNVALIdIp ARAM ETER 87 

ERROR JNVALID_PASSWORD 86 

ERROR JNVALID^PATH 253 

ERRORJNVALID_PCLASS 307 

ERROR_INVALID_PDELTA 304 

ERRORJNVALID_PROCID 303 

ERROR_INVALID_SCOPE 308 

ERROR_INVALID_SCREEN_GROUP 229 
ER ROR J NVALI D_SEGDPL 198 

ERROR_INVALID_SEGMENTJMUMBER 180 
ERROR_INVALID_SELECTOR 490 

ERRORJNVALID_SIGNAL_NUMBER 209 
ERROR_INVALID_STACKSEG 189 

ERROR_INVALID_STARTING_CODESEG 188 

ERROR_INVALID_STARTING_RING 264 
ERROR_INVALIDJARGET_HANDLE 114 
ERRORJNVALID_THREADID 309 

ERRORJNVALID_VERIFY_SWITCH 1 18 
ERRORJOPL_NOT_ENABLED 197 

ERROR_IS_JOINED 134 

ERROR_IS_JOIN_PATH 147 

ERROR_IS_JOIN_TARGET 133 

ERROR_IS_SUBSTED 135 


File not found. 

Flush buffer failed. 

General failure. 

Get buffer failed. 

Infinite loop in relocation chain segment. 

File system information not available for this file. 

Data buffer too small. 

Interrupted system call. 

Invalid access code. 

Bad physical address. 

Invalid attribute. 

Operation invalid at interrupt time. 

Invalid memory-biock address. 

Invalid call gate. 

Category for DevlOCti not defined. 

Invalid code page. 

Invalid data. 

Invalid DLL INIT ring. 

Invalid drive specified. 

Bad character in name, or bad cbName. 

DosMuxSemWait errors. 

Invalid EXE signature — file is DOS mode program or 
improper program. 

Invalid exit routine ring. 

Invalid flag number. 

Invalid frequency for beep. 

Trying to access nonexistent FSD. 

Invalid function number. 

Invalid handle. 

Non-implemented level for information retrieval or setting. 
Invalid list format. 

Invalid minimum allocation size - size is specified to be 
less than the size of the segment data in the file. 

Invalid module type - dynamic-link library file cannot be 
used as an application. Application cannot be used as a 
dynamic-link library. 

Illegal character or bad file-system name. 

Invalid ordinal. 

Invalid parameter. 

Invalid password. 

Bad pseudo device. 

Invalid P class. 

Invalid priority delta. 

Invalid process identity. 

Invalid scope. 

Invalid session. 

Invalid segment descriptor privilege level - can only 
have privilege levels of 2 and 3. 
invalid segment number. 

Not a GDT selector. 

Invalid signal number. 

Invalid stack segment. 

Invalid starting code segment, incorrect END (label) direc- 
tive. 

Invalid starting ring. 

Target handle in DosDupHandle invalid. 

Invalid thread identity. 

Invalid value passed for verify flag. 

IOPL not enabled - IOPL set to “NO” in CONFIG.SYS. 
Drive is already joined. 

Path specified is being used in join. 

Drive has previously joined drives. 

Drive is already substituted. 


Appendix A. Errors Returned from Base OS/2 Calls A-9 



E R RO R_1S_SU BST_P ATH 146 Path specified is being used in a substitute. 

ERRORJS_SUBSTTARGET 149 Cannot join or substitute drive having directory that is 

target of a previous substitute. 

E R RO R _ITE R ATE D_D AT A_EXCE E DS_64K 194 Iterated data exceeds 64KB - more than 64KB of data in 

one of the segments of the file. 

ERROR_JOIN_TO_JOIN 138 Cannot join to a joined drive. 

ERROR_JOINJTO_SUBST 140 Cannot join to a substituted drive. 

ERROR~KBD~CANNOT_CREATE_KCB 441 Unable to create kcb. 
ERROR_KBD_CODEPAGE_LOAD_INCOMPL 442 Unsuccessful code-page load. 
ERROR_KBD_DEREGISTER 411 KbdDeRegister not allowed. 

ERROR_KBdIdETACHED 464 This call not allowed for detached PID. 

ERROR_KBD_EXTENDED_SG 504 

ERROR_KBD_FOCUS_ALREADY_ACTIVE 446 Calling thread has an outstanding focus. 
ERROR~KBD~FOCUS_REQUIRED 445 Keyboard focus required. 

ERROR_KBDJNVALIDASCIIZ 408 Invalid ASCIIZ length. 

ERROR_KBD_INVALID_CODEPAGE 448 Invalid code page. 

ERROR_KBDJNVALID_CODEPAGE_ID 443 Invalid code-page identity. 
ERROR_KBDJNVALID~ECHO_MASK 377 Invalid echo mode mask. 

ERROR J<BDJNVALID_HANDLE 439 Invalid KBD handle. 

E R ROR_K B D J N V A LI D_l N PUT_M AS K 378 Invalid input mode mask. 

ERROR_KBD_INVALID_IOWAIT 375 Invalid I/O wait specified. 

ERROR_KBDJNVALIDJ_ENGTH 376 Invalid length for keyboard. 

ERROR_KBD_INVALID_MASK 409 Invalid replacement mask. 

ERROR_KBDJ<EYBOARD_BUSY 447 Keyboard busy. 

ERROR_KBD_NO_CODEPAGE_SUPPORT 444 No code page support. 

ERROR_KBD_NO_CONSOLE 500 

ERROR_KBD_NOJDEVICE 374 No device. 

ERROR_KBD_NO_MORE_HANDLE 440 Ran out of handles. 

ERROR_KBD_PARAMETER 373 Invalid parameter to keyboard. 

ERROR KBD REGISTER 410 KbdRegister not allowed. 

ERROR_KBD_SMG_ONLY 407 Valid from session manager only. 

ERROR_KBDJJNABLE_TO_FOCUS 449 Focus attempt failed. 

ERROR_LABEL_TOO_LONG 154 Volume label too big. 

ERROR_LOCKED 212 Locked error. 

ERROR_LOCK_FAILED 167 Locking failed. 

ERROR_LOCK~VIOLATION 33 Lock violation. 

ERROR_MAX_THRDS_RE ACHED 164 No more process slots. 

ERROR_META_EXPANSION_TOO_LONG 208 Meta (global) expansion is too long. 
ERROR_MODE_SWITCHJNIT 475 Mode switch initialization error. 

ERROR_MOD_NOT_FOUND 126 Module handle not found with getprocaddr, getmodhandle. 

ERROR_MONITORS_NOT_SUPPORTED 165 ERRORJ24 mapping. 

ERROR_MON_BUFFER_EMPTY 383 Buffer is empty. 

ERROR_MON_BUFFER_TOO_SMALL 382 Buffer too small. 

ERROR_MON_DATA_TOO_LARGE 384 Data record too large. 

ERROR_MON_INVAL!D_DEVNAME 380 Invalid device name string. 

ERROR_MON_INVALID_HANDLE 381 Invalid device handle. 

ERROR_MON_INVALID_PARMS 379 Invalid parameters to DosMon. 

ERROR_MORE_DATA 234 More data is available. 

ERROR_MOUSE_CANT_RESET 388 Function assigned and cannot be reset. 

ERROR_MOUSE_DEREGISTER 416 Mouse deregister not allowed. 

ERROR_MOUSE_DISPLAY_PARMS 389 Parameters invalid for display mode. 
ERROR_MOUSEJNVALID_ASCIIZ 413 Invalid ASCIIZ length. 

error!mousejnvalid_handle 502 

ERROR_MOUSEJNVALID_IOWAIT 435 Invalid parameters for lOWait. 

ERROR_MOUSEJNVALID_MASK 414 Invalid replacement mask. 

E R ROR_M OUSE J NV JENTRY_PT 391 Entry point not valid. 

ERROR_MOUSE_INV_HANDLE 386 Mouse device closed (invalid device handle). 

ERROR_MOUSE_INV_MASK 392 Function mask invalid. 

ERROR_MOUSE_INV_MODULE 390 Module not valid. 

ERROR_MOUSE_INV_PARMS 387 Parameters invalid for display mode. 

ERROR~MOUSE_NO ^CONSOLE 501 

ERROR_MOUSE_NO_DEVICE 385 Mouse device closed (invalid device handle). 

ERROR_MOUSE_REGISTER 415 Mouse register not allowed. 
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ERROR_MOUSE_SMG_ONLY 412 Valid from session manager only. 
ERROR_MOU_DETACHED 466 This call disallowed for detached pid. 

ER ROR_MOU_EXTEN DED_SG 505 

ERROR_MRJNV_IVCOUNT 320 Invalid Insertion variable count. 

ERROR_MRJNV_MSGF_FORMAT 319 Invalid message file format 
ERROR_MR_MID_NOT_FOUND 317 Message identity number not found. 

ERROR_MR_MSG_TOO_LONG 316 Message too long for buffer. 

ERROR_MR_UN_ACC_MSGF 318 Unable to access message file. 

ERROR_MR_UN_PERFORM 321 Unable to perform function. 

ERROR_NEGATIVE_SEEK 131 Attempting seek to negative offset. 

E R ROR_N ESTI NG_NOT_ALLOWE D 215 Nesting not allowed. 

ERROR_NET_WRITE_FAULT 88 Network device fault. 

ERROR_NLS_BAD_TYPE 400 Selected type does not exist. 

ERROR_NLS_NO_COUNTRY_FILE 396 Cannot find COUNTRY.SYS file. 
ERROR_NLS_NO_CTRY_CODE 398 Country code not found. 

ERR0r”nLS” 0PEN_FAILED 397 Cannot open COUNTRY.SYS file. 

ERROR_NLS_TABLE_TRUNCATED 399 Table returned information truncated, buffer too small. 
ERROR_NLS_TYPE_NOT_FOUND 401 Selected type not in file. 

ERROR_NOT_CURRENT_CTRY 204 Not current country. 

ERROR JMOT_DESCENDANT 305 Not descendant. 

ERROR_NOT_DOS_DISK 26 Unknown media type. 

ERROR_NOT_ENOUGH_M EMORY 8 Insufficient memory. 

ERROR_NOTJENOUGH_SELECTORS_AVA 489 Not enough GDT selectors to satisfy request. 
ERROR_NOT_FROZEN 90 System error. 

ERROR_NOT_JOINED 136 Cannot delete drive that is not joined. 

ERROR_NOT_LOCKED 158 Segment not locked. 

ERROR_NOT_READY 21 Drive not ready. 

ERROR_NOT_SAME_DEVICE 17 Not same device. 

ERROR_NOT_SESSION_MANAGER 306 Requestor not session manager. 

E R ROR_NOT_SU BSTE D 137 Cannot delete drive that is not substituted. 

ERRORNOTSUPPORTED 50 Network request not supported. 

ERROR_NO_CHILDREN 228 No child process. 

ERROR_NO_CHILD_PROCESS 184 No child process to wait for. 

ERROR_NO_COUNTRY_OR_CO DEPAGE 398 Country code not found. 

ERROR^NOJDATA 232 No data available on non-blocking read. 

ERRORNOJTEMS 93 No items to work on. 

ERRORJMO_META_MATCH 257 String doesn't match expression. 

ERROR_NO_MORE_FILES 18 No more files. 

ERROR_NO_MORE_ITEMS 259 DosQFSAttach ordinal query. 

ERROR_NO_MORE_SEARCH_HANDLES 113 Cannot allocate another search structure and handle. 
ERROR_NO_PROC_SLOTS 89 No process slots available. 

ERROR_NO_SIGNAL_SENT 205 No signal sent - no process in the command subtree has 

a signal handler. 

ERROR_NO_VOLUME_LABEL 125 No volume label found with DosQFsInfo command. 

ERROR_OPEN_FAILED 1 10 Open/create failed due to explicit fail command. 

ERROR_OPLOCKED_FILE 268 Oplocked file. 

ERROR_OPLOCK_THREAD_EXISTS 269 Oplock thread exists. 

ERROR_OUT_OF_PAPER 28 Printer out of paper. 

ERROR_OUT_OF_STRUCTURES 84 Too many redirections. 

ERROR_PATHJ3USY 148 Path specified is being used by another process. 

ER ROR_P ATH_NOT_FOUN D 3 Path not found. 

ERROR_PIPE_BUSY 231 Pipe is busy. 

ERROR_PIPE_NOT_CONNECTED 233 Pipe was disconnected by server. 

ERROR_PROC_NOTJFOUND 127 Procedure address not found with getprocaddr. 

ERROR_PROTECTION_VIOLATION 115 Bad user virtual address. 

ERROR_QUE_CURRENT_NAME 329 Current queue name does not exist. 

ERROR_QUE_DUPLICATE 332 Duplicate queue name. 

ERROR_QUEJELEMENT_NOT_EXIST 333 Queue element does not exist. 

ERROR_QUE_EMPTY 342 Queue is empty. 

ERROR_QUE_INVALID_HANDLE 337 Invalid queue handle. 

ERROR_QUE_INVALID_NAME 335 Invalid queue name. 

ERROR_QUEJNVALID_PRIORITY 336 Invalid queue priority parameter. 

ERROR_QUE_INVALID_WAIT 433 NoWait parameter out of bounds. 
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ERROR_QUE_LINK_NOT_FOUND 338 
ERROR_QUE_MEMORY_ERROR 339 

ERROR_QUE_NAME_NOT_EXIST 343 
ERROR_QUE_NOTJNITIALIZED 344 

ERROR_QUE_NO_M EMORY 334 

ERROR_QUEJPREV_AT_END 340 

ERROR_QUE_PROC_NOT_OWNED 330 
ERROR_QUE_PROC_NO_ACCESS 341 

ERROR_QUE_PROC_OWNED 331 

ERRORJ3UEJJNABLEJTO_ACCESS 345 
ERROR_QUEJJNABLE_TO_ADD 346 
ERROR_QUE_UNABLE_TO_INIT 347 

ERROR_READ_FAULT 30 

ERROR_RELOC_CHAIN_XEEDS_SEGLIM 201 
ERROR_RING2SEG_MUST_BE_MOVABLE 200 
ERROR_RING2_STACK_IN_USE 207 

ERROR_SAME_DRIVE 143 

ERROR_SCS_CALL 364 

ERROR_SCSJNVALID_FUNCTION 424 
ERROR_SCS_NOT_SESSION_MGR 425 
ERROR_SCS_NOT_SHELL 420 

ERROR_SCS_SG_NOTFOUND 419 

ERROR_SCS_VALUE 365 

ERROR_SEARCH_STRUC_REUSED 260 
ERROR_SECTOR_NOT_FOUND 27 

ERROR_SEEK 25 

ERROR_SEEK_ON_DEVICE 132 

ERROR_SEM_IS_SET 102 

ERROR_SEM_NOT_FOUND 187 

ERROR_SEM_OWNER_DIED 105 

ERROR_SEM_TIMEOUT 121 

ERROR_SEM_USER_LIMIT 106 

ERROR_SGS_NOT_SESSION_MGR 368 
ERROR_SHARING_BUFFER_EXCEEDED 36 
ERROR_SHARING_VIOLATION 32 

ERROR_SIGN APPENDING 162 

ERROR_SIGNAL_REFUSED 156 

ERROR_SMG_BAD_ACT!ON 417 

ERROR_SMG_BAD_RESERVE 459 

ERROR_SMG_BAD_STATUSREQ 432 

ERROR_SMGJ3RP_NOT_FOUND 371 

ERROR_SMG_INVALID_BOND_OPTION 455 
ERROR_SMG JNVALIDCALL 41 8 

ERROR_SMGJNVALID_DATAJ-ENGTH 461 
ERROR_SMGJNVALID_DEBUG_PARMS 503 
ERROR_SMGJNVALIDJCON_FlLE 506 
ERROR_SMGJNVALIDJNHERIT_OPT 493 
ERROR_SMGJNVALID_PGM_CONTROL 492 
ERROR_SMGJNVALID_PROGRAM_TYPE 491 
ERROR_SMG_INVALID_RELATED_OPT 454 
ERROR_SMG_INVALID_SELECT_OPT 456 
ERROR_SMG_INVALID_SESSION_ID 369 
ERROR_SMG_INVALID_SGlD 369 

ERROR_SMGJNVAUD_START_MODE 453 
ERROR_SMGJNVALID_STOP_6pTION 458 
ERROR_SMGJNVAUDJTRACE_pPTlON 478 
ERROR_SMG_NOSG 370 

ERROR_SMG_NOT_BASESHELL 431 
ERROR_SMG_NOT_BOUND 462 

ERROR_SMG_NO_HARD_ERRORS 481 
ERROR_SMG_NO_SESSIONS 370 


Queue link not found. 

Queue memory error. 

Queue name does not exist. 

Queues not initialized. 

Inadequate queue memory. 

Previous queue element was at end of queue. 

Current process does not own queue. 

Process does not have access to queues. 

Current process owns queue. 

Unable to access queues. 

Unable to add new queue. 

Unable to initialize queues. 

Read fault. 

Relocation chain exceeds segment limit. 

Privilege level 2 segment must be movable. 

Privilege level 2 stack in use. 

Cannot join or substitute a drive to a directory on the 
same drive. 

Call issued by other than sm 
Caller invalid function. 

Caller not session manager. 

Caller is not shell. 

New session number. 

Value is not for save or restore. 

DOS mode findfirst/next search structure reused. 
Sector not found. 

Seek error. 

Application trying to seek on device or pipe. 
DosCloseSem found semaphore set. 

Semaphore does not exist. 

Previous semaphore owner terminated without freeing 
semaphore. 

Time out occurred from semaphore API function. 
Semaphore limit exceeded. 

Caller not session manager. 

Sharing buffer overflow. 

Sharing violation. 

Signal already pending. 

Signal refused. 

Invalid action specified. 

Reserved parameters not zero. 

Invalid status requested. 

Session not found. 

Invalid session bond option. 

INIT called more than once or invalid session identity. 
Invalid data length. 


Bad inherit option. 

Invalid program control. 

Invalid program type. 

Invalid session start related option. 
Invalid session select option. 

Invalid session ID. 

Invalid session identity. 

Invalid session start mode. 

Invalid session stop option. 

Invalid start session trace indicator. 
No sessions available. 

Caller is not the base shell. 

Parent not bound. 

No session manager hard errors. 

No sessions available. 
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ERROR_SMG_PROCESS_NOT_PARENT 460 
ERROR_SMG_RETRY_SUB_ALLOC 463 
ERROR_SMG_SESSION_NON_SELECT 450 
ERROR_SMG_SESSlON_NOT_FOREGRND 451 
ERROR_SMG_SESSION_NOT_FOUND 371 
ERROR_SMG_SESSION_NOT_PARENT 452 
E R R 0 R_S M G_SET_TITLE 372 

ERROR_SMG_STARTJN_BACKGROUND 457 
ERROR_STACKJN_HIGH_M EMORY 218 
ERROR_SUBST_TO_JOIN 141 

ERROR_SUBST_TO_SUBST 139 
ERROR_SWAPIN_FAILED 169 

ERROR_SWAPIO_FAILED 168 

E R R O R_S YSTE M_TR AC E 150 

ERROR_SYSJNTiRNAL 328 

ERRORJTHREAD_1_INACTIVE 210 

ERROR_TOO_MANY_MODULES 214 

ERROR_TOO_MANY_MUXWAITERS 152 
ERROR_TOO_MANY_OPENJFILES 4 

ERROR_TOO_MANY_SEMAPHORES 100 
ERROR_TOO_MANY_SEM_REQUESTS 103 
ERROR_TOO_MANY_TCBS 1 55 

ERROR JTOO_MUCH_STACK 262 

ERROR_TRANSFERjrOO„LONG 222 

ERROR_TS_DATETIME 327 

ERROR_TS_HANDLE 326 

ERROR_TS_NOTIMER 324 

ERROR_TS_SEMHANDLE 323 

ERROR_TS_WAKEUP 322 

ERROR JJNCERTAIN_MEDIA 163 

ERROR_UNC_DRIVER_NOTJNSTALLED 166 
ERROR JJNEXPECTED_SLOT_RETURNED 477 
ERROR_VC_DISCONNECTED 240 

ERROR_VIOKBD REQUEST 116 

ERROR_VIO_APTR 351 

ERROR_VIO_ASSOCIATED_DC 499 

ERROR_VIO_ATTR 357 

ERROR_VIO_BAD_CP 469 

ERROR_VIO_BAD_RESERVE 486 

ERROR_VIO_BOTROW 361 

ERROR_VIO_COL 359 

ERROR_VIO_CPTR 353 

ERROR_VIO_DEREGISTER 404 

ERROR_VIO_DETACHED 465 

E R ROR_V 1 0_EX I STI N G_POP U P 406 

ERROR_VIO_EXTENDED_SG 494 

ERROR_VIO_FONT 467 

ERROR_VIO_FUNCTION_OWNED 422 
ERROR_VIO_ILLEGAL_DURING_LOCK 437 
ERROR_VIOJLLEGAL_DURING_POPUP 430 
ERROR_VIOJNTERNAL_RESOURCE 479 
ERROR_VIOJNVALID_ASC!IZ 403 

ERROR_VIOJNVALID_HANDLE 436 

ERROR_VIOJNVALID_LENGTH 438 

ERROR_VIO_INVALID_MASK 349 

ERROR_VIOJNVALID_PARMS 421 

ERROR_VIO_IN_BG 429 

ERROR_VIO_LEFTCOL 363 

ERROR_VIO_LOCK 434 

ERROR_VIO_LPTR 354 

ERROR_VIO_MODE 355 

ERROR_VIO_NA_CP 471 

ERROR_VIO_NOT PRES MGR SG 495 


Session parent process already exists. 

Retry request block allocation. 

Session is not selectable. 

Parent/child session not foreground. 

Session not found. 

Not parent of requested child. 

Title sent by shell or parent cannot be changed. 
Session started in background. 

Stack in high memory. 

Cannot substitute to a joined drive. 

Cannot substitute to a substituted drive. 

Swap in failed. 

Swap 10 failed. 

System trace error. 

Internal system error. 

Inactive thread. 

Too many modules. 

System limit of 100 entries reached. 

Too many open files (no handles left). 
User/system open semaphore limit exceeded. 
Too many exclusive semaphore requests. 
Cannot create another TCB. 

Stack request exceeds system limit. 

Transfer is too long. 

Date or time invalid. 

Invalid timer handle. 

No timers available. 

Invalid system semaphore. 

Unable to wake up. 

ERRORJ24 mapping. 

Default redir return code 
Internal error. 

Session was dropped due to errors. 

Error on display write or keyboard read. 

Invalid pointer to attribute. 

Invalid cursor attribute value. 

Invalid code page specified. 

Reserved parameter is not zero. 

Invalid BotRow value. 

Invalid column value. 

Invalid pointer to column. 

VioDeRegister not allowed. 

This call disallowed for detached pid. 

Pop-up window on screen (NoWait). 

No font available to support mode. 

Save/restore already owned. 

Function not allowed during screen lock. 
Function not allowed during pop-up window. 

VIO internal resource error. 

Invalid ASCIIZ length. 

Invalid VIO handle. 

Invalid VIO length. 

Invalid function replaced. 

Invalid parameters passed. 

Function invalid in background. 

Invalid left column value. 

Error returned from Scroll Lock. 

Invalid pointer to length. 

Unsupported screen mode. 

Current display does not support code page. 
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ERROR_VIO_NO_CP 470 

ERROR_VIO_NO_MODE_THREAD 427 
ERROR_VIO_NO_MORE_HANDLES 497 
ERROR_VIO_NO_POPUP 405 

E R ROR_V 1 0_N0_SAVE_REST O R E_TH D 428 
ERROR_VIO_PTR 350 

ERROR_VIO_REGISTER 426 

ERROR_VIO_RETURN 423 

ERROR_VIO_RIGHTCOL 362 

ERROR_VIO_ROW 358 

ERROR_VIO_RPTR 352 

ERROR_VIO_SEE_ERROR_LOG 498 

ERROR_VIO_SHELL_INIT 480 

ERROR_VIO_SHIELD_OWNED 496 

ERROR_VIO_SMG_ONLY 402 

ER ROR_V 1 0_TOPROW 360 

ERROR_VIO_TRANSPARENT_POPUP 483 
ERROR_VIO_UNLOCK 367 

ERROR_VIOJJSER_FONT 468 

ERROR_VIO_WAIT_FLAG 366 

ERROR_VIO_WIDTH 356 

ERROR_VOLUME_CHANGED 270 

ERROR_WAIT_NO_CHILDREN 128 

ERROR_WRITE_FAULT 29 

ERROR_WRITE_PROTECT 19 

ERROR_WRONG_DISK 34 

ERROR_ZERO__SELECTORS_REQUESTED 488 
ERROR_ZOMBIE_PROCESS 217 

ERRJTSTDUP 92 

ERR_TSTOVFL 91 

NO_ERROR 0 

NO_ERROR_MOUSEJMO_DATA 393 
NO_ERROR_MOUSE_PTR_DRAWN 394 


System displays do not support code page. 
No mode restore thread in SG. 

Pop-up window not allocated. 

No save/rest thread in SG. 

Invalid pointer to parameter. 

Vio register not allowed. 

Non-destruct return (undo). 

Invalid right column value. 

Invalid row value. 

Invalid pointer to row. 

VIO shell initialization error. 

Valid from session manager only. 

Invalid TopRow value. 

Error during VIO pop-up window. 

Screen not previously locked. 

User font active. 

Invalid wait flag setting. 

Invalid cursor width value. 

Volume changed. 

DosCwait finds no children. 

Write fault 

Attempt to write on write-protected diskette, 
Invalid disk change. 

At least one selector must be requested. 
Zombie process. 

Timer service table duplicate. 

Timer service table overflow. 

No error occurred. 

No valid data. 

Pointer drawn. 
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Index 


A 

application type 2-243 
ASCII mode 3-29 

attach a pseudo-character device name to an 
FSD 2-111 

attach a volume to a remote file system 2-111 
attached remote file system, query information from 
a 2-257 

attributes, file 2-255 


B 

BINARY mode 3-29 
Buffer 

display video 5-79 
flush keystroke 3-7 
get physical video 5-20 
get video 5-5 
register as monitor 2-191 
reset 2-11 


C 

case map 2-16 

characters, global file name 2-56 
Child 

wait for termination 2-42 
Code Page 

get process 2-122 
get video 5-11 
set 2-320 
set process 2-344 
set video 5-62 
Code Segment 

create cs alias 2-32 
collate table, get 2-120 
constant names 1-1 
control, file system 2-113 
copy file 2-30 
country information 2-124 
Critical Section 
enter 2-58 
exit 2-76 
of execution 2-58 


D 

date, get 2-128 
date, set 2-322 

detach a pseudo-character device name from an 
FSD 2-111 

detach a volume from a remote file system 2-111 
Device 

configuration 2-47 
installed 2-47 
I/O control 2-49, 2-51 
Device Monitor 

close connection 2-187 
open connection 2-188 
read input 2-189 
register buffers 2-191 


Device Monitor (continued) 
write output 2-193 
device name, character 2-257 
device name, pseudo 2-257 
Directory 

change current 2-18 
query current 2-245 
directory information, enumerate 2-59 
directory information, query 2-271 
directory information, set 2-340 
Disk 

partitionable support 2-231 
query current 2-247 
select drive 2-299 
display mode table 5-72 
DosAllocHuge 2-2 
DosAllocSeg 2-5 
DosAllocShrSeg 2-8 
DosBeep 2-10 
Dos Buf Reset 2-11 
DosCallback 2-13 
DosCalINmPipe 2-14 
DosCaseMap 2-16 
DosChDir 2-18 
DosChgFilePtr 2-20 
DosCLIAccess 2-22 
DosClose 2-23 
DosCloseQueue 2-25 
DosCloseSem 2-26 
DosConnectNmPipe 2-28 
DosCopy 2-30 
DosCreateCSAIias 2-32 
DosCreateQueue 2-34 
DosCreateSem 2-36 
DosCreateThread 2-39 
DosCwait 2-42 
Dos Delete 2-45 
DosDevConfig 2-47 
DosDevlOCtl 2-49 
DosDevlOCtl2 2-51 
DosDisConnectNmPipe 2-53 
DosDupHandle 2-54 
DosEditName 2-56 
DosEnterCritSec 2-58 
DosEn urn Attribute 2-59 
DosErrClass 2-62 
DosError 2-65 
DosExecPgm 2-67 
DosExit 2-73 
DosExitCritSec 2-76 
DosExitList 2-77 
DosFilelO 2-79 
DosFileLocks 2-82 
DosFindClose 2-85 
DosFindFirst 2-86 
DosFindFirst2 2-91 
DosFindNext 2-99 
DosFlag Process 2-103 
DosFreeModule 2-106 
DosFreeResource 2-108 
DosFreeSeg 2-109 
DosFSAttach 2-111 



DosFSCtl 2-113 
DosFSRamSemClear 2-115 
DosFSRamSemRequest 2-117 
DosGetCollate 2-120 
DosGetCp 2-122 
DosGetCtrylnfo 2-124 
DosGetDateTime 2-128 
DosGetDBCSEv 2-131 
DosGetEnv 2-133 
DosGetHugeShift 2-135 
DosGetlnfoSeg 2-136 
DosGetMachineMode 2-142 
DosGetMessage 2-143 
DosGetModHandle 2-146 
DosGetModName 2-147 
DosGetPID 2-148 
DosGetPPID 2-151 
DosGetProcAddr 2-153 
DosGetPrty 2-154 
DosGetResource 2-157 
DosGetResource2 2-159 
DosGetSeg 2-161 
DosGetShrSeg 2-162 
DosGiveSeg 2-165 
DosHoldSignal 2-166 
DosInsMessage 2-169 
DosKillProcess 2-171 
DosLoadModule 2-174 
DosLockSeg 2-176 
DosMakeNmPipe 2-177 
DosMakePipe 2-180 
DosMemAvail 2-181 
DosMkDir 2-182 
DosMkOir2 2-183 
DosMonClose 2-187 
DosMonOpen 2-188 
DosMonRead 2-189 
DosMonReg 2-191 
DosMonWrite 2-193 
DosMuxSemWait 2-196 
DosNewSize 2-200 
DosOpen 2-201 
DosOpenQueue 2-214 
DosOpenSem 2-215 
DosOpen2 2-207 
DosPeekNmPipe 2-218 
DosPeekQueue 2-220 
DosPFS Activate 2-222 
DosPFSCIoseUser 2-224 
DosPFSInit 2-225 
DosPFSQueryAct 2-227 
DosPFSVerifyFont 2-229 
DosPhysicalDisk 2-231 
DosPortAccess 2-233 
DosPtrace 2-235 
DosPurgeQueue 2-241 
DosPutMessage 2-242 
DosQAppType 2-243 
DosQCurDir 2-245 
DosQCurDlsk 2-247 
DosQFHandState 2-248 
DosQFilelnfo 2-250 
DosQFileMode 2-255 
DosQFSAttach 2-257 
DosQFSInfo 2-260 
DosQHandType 2-263 
DosQNmPHandState 2-265 


DosQNmPipelnfo 2-267 
DosQNmPipeSemState 2-269 
DosQ Path Info 2-271 
DosQSysInfo 2-277 
DosQueryQueue 2-278 
DosQVerify 2-279 
DosRead 2-281 
DosReadAsync 2-283 
DosReadQueue 2-285 
DosReallocHuge 2-287 
DosReallocSeg 2-269 
DosResumeThread 2-291 
DosRmDIr 2-293 
DosR2StackRealloc 2-280 
DosScanEnv 2-294 
DosSearchPath 2-296 
DosSelectDisk 2-299 
DosSelectSession 2-300 
DosSemClear 2-301 
DosSemRequest 2-303 
DosSemSet 2-306 
DosSemSetWait 2-309 
DosSemWait 2-313 
DosSendSignal 2-317 
DosSetCp 2-320 
DosSetDateTime 2-322 
DosSetFHandState 2-324 
DosSetFllelnfo 2-326 
DosSetFileMode 2-331 
DosSetFSInfo 2-333 
DosSetMaxFH 2-335 
DosSetNmPHandState 2-336 
DosSetNmPipeSem 2-338 
DosSetPathlnfo 2-340 
DosSetProcCp 2-344 
DosSetPrty 2-345 
DosSetSession 2-349 
DosSetSigHandler 2-352 
DosSetVec 2-356 
DosSetVerify 2-358 
DosShutdown 2-360 
DosSIzeSeg 2-359 
DosSleep 2-361 
DosSMRegisterDD 2-364 
DosStartSession 2-366 
DosStopSession 2-373 
DosSubAlloc 2-375 
DosSubFree 2-376 
DosSubSet 2-377 
DosSuspendThread 2-379 
DosTimerAsync 2-381 
DosTimerStart 2-383 
DosTimerStop 2-385 
DosTransactNmPipe 2-387 
DosUnlockSeg 2-389 
DosWaitNmPipe 2-390 
DosWrite 2-391 
DosWriteAsync 2-394 
DosWriteQueue 2-396 
Dynamic Link 

free module 2-106 
get module handle 2-146 
get module name 2-147 
get procedure address 2-153 
load module 2-174 


X-2 Control Program Programming Reference 



E 

enumerate 

a directory's information 2-59 
a file’s information 2-59 
a subdirectory's information 2-59 
Environment String 
get address 2-133 
equipment check 2-47 
error code classification 2-62 
error descriptions 
base OS/2 calls A-1 
Errors 

classify codes 2-62 
processing 2-65 
executable file 2-243 


F 

File 

change size 2-200 
delete 2-45 

find first matching 2-86, 2-91 
find next matching 2-99 
lock manager 2-82 
move 2-194 
open 2-201,2-207 
query information 2-250 
query mode 2-255 
query system information 2-260 
read 2-281 

read asynchronous 2-283 
search path for name 2-296 
set information 2-326 
set mode/attribute 2-331 
set system information 2-333 
write to, asynchronous 2-394 
write to, synchronous 2-391 
file access, lock 2-79 
file access, unlock 2-79 
file attributes 2-255 
File Handle 
close 2-23 
duplicate 2-54 
query state 2-248 
set maximum 2-335 
set state 2-324 

file information, enumerate 2-59 

file information, query 2-271 

file information, set 2-340 

file 10, read 2-79 

file 10, write 2-79 

file lock manager 2-82 

file name, search 2-296 

file pointer, change 2-20 

file system control 2-113 

file system, DosShutdown 2-360 

file, copy 2-30 

file, move or rename a 2-194 

find handle, close 2-85 

Flags 

set external event 2-103 
Font 

activate 2-222 
initialize 2-225 
query active 2-227 
verify 2-229 


foreground session, select 2-300 
function descriptions 
conventions used 1-1 
notation 1-1 

G 

Get Version Number 2-163 
global editing characters 2-56 
global file name characters 2-56 
global search characters 2-56 

H 

Handle 

query type 2-263 
hard error processing 2-65 

I 

implicit pointer 1-1 
I/O Privilege 

disable/enable interrupts 2-22 
port access 2-233 
request CLI/STI 2-22 
request/ release access 2-233 

K 

KbdCharln 3-2 
KbdClose 3-5 
KbdDeRegister 3-6 
KbdFlushBuffer 3-7 
KbdFreeFocus 3-8 
KbdGetCp 3-9 
KbdGetFocus 3-10 
KbdGetHWId 3-11 
KbdGetStatus 3-13 
KbdOpen 3-16 
KbdPeek 3-17 
KbdRegister 3-20 
KbdSetCp 3-22 
KbdSetCustXt 3-24 
KbdSetFgnd 3-25 
KbdSetStatus 3-26 
KbdStringln 3-29 
KbdSynch 3-31 
KbdXIate 3-32 
Keyboard 
close 3-5 

deregister subsystem 3-6 
free focus 3-8 
get focus 3-10 
get status 3-13 
open 3-16 
peek character 3-17 
peek scan code 3-17 
read character 3-2 
read character string 3-29 
read scan code 3-2 
register subsystem 3-20 
scan code 3-2 
set priority 3-25 
set status 3-26 
synchronize access 3-31 
translate scan code 3-32 


Index 
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move a file or subdirectory 2-194 


L 

lock file access 2-79 


M 

matching file, find first 2-86, 2-91 
matching file, find next 2-99 
Memory 

allocate huge 2-2 
allocate segment 2-5 
allocate shared segment 2-8 
change huge size 2-287 
free suballocated 2-376 
get largest free block 2-181 
get shared segment 2-162 
set allocated 2-377 
suballocate segment 2-375 
Messages 

output text to handle 2-242 
system 2-143 
variable text 2-143 
variable text strings 2-169 
mode, display table 5-72 
module definition file, NAME statement 2-243 
MouClose 4-2 
MouDe Register 4-3 
MouDrawPtr 4-4 
MouFlushQue 4-5 
MouGetDevStatus 4-6 
MouGetEventMask 4-7 
MouGetNumButtons 4-8 
MouGetNumMickeys 4-9 
MouGetNumQueEl 4-10 
MouGetPtrPos 4-12 
MouGetPtrShape 4-14 
MouGetScaleFact 4-17 
MoulnitReal 4-19 
MouOpen 4-21 
MouReadEventQue 4-23 
MouRegister 4-26 
MouRemovePtr 4-29 
Mouse 

get scale factor 4-17 
get synchronous access 4-42 
initialize DOS mode 4-19 
register subsystem 4-26 
set event mask 4-33 
set scale factor 4-40 
Mouse Device 
close 4-2 
open 4-21 
set status 4-31 
Mouse Pointer 
draw 4-4 
remove 4-29 
set position 4-35 
set shape 4-37 
Mouse Queue 
flush 4-5 
read event 4-23 
MouSetDevStatus 4-31 
MouSetEventMask 4-33 
MouSetPtrPos 4-35 
MouSetPtrShape 4-37 
MouSetScaleFact 4-40 
MouSynch 4-42 


N 

name editing 2-56 
NAME statement 2-243 
Named Pipe 
close 2-53 
connect 2-28 
create 2-177 
disconnect 2-53 
instance availability 2-390 
make 2-177 
operations, query 2-269 
peek 2-218 

perform transaction 2-387 
procedure call 2-14 
query 2-265 
query info 2-267 
read 2-218 
set handle state 2-336 
set semaphore 2-338 
wait 2-390 

notation conventions 1-1 
NULL 1-1 


o 

Open a File 2-201, 2-207 

P 

Pipes 

create 2-180 
pointer, implicit 1-1 
power off, DosShutdown 2-360 
privilege level 2 stack 2-280 
Process 

delay execution 2-361 
get ID 2-148 
get parent ID 2-151 
get priority 2-154 
routine list termination 2-77 
set code page 2-344 
set priority 2-345 
termination 2-171 
processor mode 2-142 
Program 

debug interface 2-235 
execution 2-67 
exit 2-73 

pseudo device name 2-257 
pseudo-character device name 2-111, 2-257 
pseudo-character device name attached to an FSD, 
query 2-257 

Q 

query a directory's information 2-271 
query a file's information 2-271 
query a subdirectory's information 2-271 
query info about a pseudo-character device attached to 
an FSD 2-257 

query info about an attached remote file system 2-257 

query system variables 2-277 

Queue 

close 2-25 
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Queue (continued) 
make queue 2-34 
open 2-214 
peek 2-220 
purge 2-241 
query size 2-278 
query, verify setting 2-279 
read 2-285 
write to 2-396 


R 

read file 10 2-79 

register session switch notification 2-364 

rename a file or subdirectory 2-194 

reset, buffers 2-11 

resource 2-108, 2-159 

resource segment 2-157 

return code classification 2-62 

routine list 2-77 

S 

scan code, translate 3-32 
Segment 

access shared segment 2-161 
allocate 2-5 
allocate shared 2-8 
change size 2-289 
free suballocated memory 2-376 
get shared segment 2-162 
give access to 2-165 
lock 2-176 

scan environment 2-294 
suballocate memory 2-375 
system variable address 2-136 
unlock 2-389 
segment size 2-359 
Semaphore 
clear 2-115 
clear (release) 2-301 
close, system 2-26 
create system semaphore 2-36 
open, system 2-215 
request 2-117,2-303 
set owned 2-306 
set/wait for clear 2-309 
wait N to clear 2-196 
wait to clear 2-313 
Session 

start 2-366 
stop 2-373 

session status, set 2-349 
set a directory’s information 2-340 
set a file’s information 2-340 
shift count 2-135 
Shutdown 2-360 
signal focus 2-353 
Signal Handler 
set 2-352 
Signals 

disable/enable 2-166 
send control break 2-317 
send control C 2-317 
speaker sound 2-10 
Subdirectory 

create 2-182,2-183 


Subdirectory (continued) 
remove 2-293 

subdirectory information, enumerate 2-59 
subdirectory information, query 2-271 
subdirectory, move or rename a 2-194 
system variables, query 2-277 

T 

Thread 

create 2-39 
restart 2-291 
suspend execution 2-379 
time delay, start Async 2-381 
Timer 

start 2-383 
stop 2-385 
time, get 2-128 
time, set 2-322 
TRC_* values 2-239 

U 

unlock file access 2-79 

V 

Vector 

DBCS 2-131 
environmental 2-131 
vector, set 2-356 
verify switch, set 2-358 
version number, get 2-163 
Video 

ANSI status 5-4 
configuration 5-7 
deallocate pop-up 5-3 
deregister subsystem 5-2 
get font 5-15 
get state 5-22 
register subsystem 5-43 
set ANSI 5-61 
set code page 5-62 
set font 5-67 
set state 5-74 
Video Cursor 

get position 5-12 
get type 5-13 
set position 5-64 
set type 5-65 
Video Mode 
display 5-17 
restore 5-30 
restore wait 5-32 
set display 5-69 
Video pop-up 
allocate 5-34 
Video Read 

character string 5-41 
char/attr string 5-39 
Video Screen 
lock 5-50 
print 5-37 
print toggle 5-38 
save redraw undo 5-46 
save redraw wait 5-48 
scroll down 5-52 
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Video Screen (continued) 
scroll left 5-54 
scroll right 5-56 
scroll up 5-58 
unlock 5-60 
Video Write 

char string w/attrib 5-84 
character string 5-82 
char/attr string 5-80 
N attributes 5-86, 5-88 
N characters 5-88, 5-90 
TTY string 5-92 
VioDeRegister 5-2 
VioEndPopUp 5-3 
VioGetAnsi 5-4 
VioGetBuf 5-5 
VioGetConflg 5-7 
VioGetCp 5-11 
VioGetCurPos 5-12 
VioGetCurType 5-13 
VioGetFont 5-15 
VioGetMode 5-17 
VioGetPhysBuf 5-20 
VioGetState 5-22 
VioGlobalReg 5-27 
VioModeUndo 5-30 
VioModeWait 5-32 
VioPopUp 5-34 
VioPrtSc 5-37 
VioPrtScToggle 5-38 
VioReadCellStr 5-39 
VioReadCharStr 5-41 
VioRegister 5-43 
VioSavRedrawUndo 5-46 
VioSavRedrawWait 5-48 
VioScrLock 5-50 
VioScrollDn 5-52 
VioScrolILf 5-54 
VioScrolIRt 5-56 
VioScrollUp 5-58 
VioScrUnLock 5-60 
VioSetAnsi 5-61 
VioSetCp 5-62 
VioSetCurPos 5-64 
VioSetCurType 5-65 
VioSetFont 5-67 
VioSetMode 5-69 
VioSetState 5-74 
VioShowBuf 5-79 
VioWrtCellStr 5-80 
VioWrtCharStr 5-82 
VioWrtCharStrAtt 5-84 
VioWrtNAttr 5-86 
VioWrtNCell 5-88 
VioWrtNChar 5-90 
VioWrtTTY 5-92 


W 

write file IO 2-79 
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